TextGenerator

The main class for generating text.

import { TextGenerator, SimpleFakerAdapter } from 'malarky';

const generator = new TextGenerator(options);

Constructor

new TextGenerator(options: GeneratorInitOptions)

GeneratorInitOptions

interface GeneratorInitOptions {
  fakerAdapter: IFakerAdapter; // Required: word generation fallback
  lexicon?: Lexicon; // Optional: lexicon for guided generation
  rng?: IRng; // Optional: custom RNG implementation
  config?: Partial<GeneratorConfig>; // Optional: override default config
  enableTrace?: boolean; // Optional: enable tracing (default: false)
}

The only required field is fakerAdapter. The built-in SimpleFakerAdapter provides a fixed set of English words with no external dependencies. For more variety, use FakerJsAdapter with @faker-js/faker (see Faker Integration).

Methods

Method	Returns	Description
sentence(opts?)	string \| GeneratedText	Generate one sentence
paragraph(opts?)	string \| GeneratedText	Generate a paragraph
textBlock(opts?)	string \| GeneratedText	Generate multiple paragraphs
setSeed(seed: number)	void	Set RNG seed for reproducibility
setLexicon(lexicon: Lexicon)	void	Load or replace lexicon at runtime
setArchetype(name: string)	void	Activate a style preset
getTransformRegistry()	TransformRegistry	Access the transform registry

When enableTrace is false (default), generation methods return a plain string. When true, they return a GeneratedText object containing the text, trace data, and metadata.

Usage examples

Basic generation

const generator = new TextGenerator({
  fakerAdapter: new SimpleFakerAdapter(),
});

generator.setSeed(42);

const sentence = generator.sentence();
// "Generally, the change called."

const paragraph = generator.paragraph({ sentences: 3 });
// Three sentences of plausible nonsense

const textBlock = generator.textBlock({ paragraphs: 2 });
// Two paragraphs of malarky

With a lexicon

import { loadLexiconFromString } from 'malarky';
import { readFileSync } from 'fs';

const lexicon = loadLexiconFromString(readFileSync('./corp.json', 'utf-8'));

const generator = new TextGenerator({
  fakerAdapter: new SimpleFakerAdapter(),
  lexicon,
});

generator.setArchetype('corporate');
console.log(generator.paragraph());

With tracing enabled

const generator = new TextGenerator({
  fakerAdapter: new SimpleFakerAdapter(),
  enableTrace: true,
});

const result = generator.sentence();
// result is a GeneratedText object
console.log(result.text);
console.log(result.meta.archetype);
console.log(result.trace.paragraphs[0].sentences[0].template);

See Guides > Tracing for full trace documentation.

Registering custom transforms at runtime

Use getTransformRegistry() when you want to register or inspect transforms on a specific generator instance:

import type { IOutputTransform } from 'malarky';

const shoutTransform: IOutputTransform = {
  id: 'shout',
  version: '1.0.0',
  capabilities: {
    requiresTrace: false,
    posAware: false,
    deterministic: true,
    safeToStack: true,
    preferredOrder: 50,
  },
  validateParams: () => ({ valid: true, errors: [] }),
  apply: ({ tokens }) => ({
    tokens: tokens.map((token) =>
      token.type === 'word' && !token.meta?.protected
        ? { ...token, value: token.value.toUpperCase() }
        : token
    ),
  }),
};

generator.getTransformRegistry().register(shoutTransform);

const result = generator.sentence({
  outputTransforms: {
    enabled: true,
    pipeline: [{ id: 'shout' }],
  },
});

See Output Transforms > Custom Transforms for the full interface, registry API, and implementation tips.

Adapters

SimpleFakerAdapter

The built-in adapter with no external dependencies. Uses a fixed vocabulary of common English words.

import { SimpleFakerAdapter } from 'malarky';

const generator = new TextGenerator({
  fakerAdapter: new SimpleFakerAdapter(),
});

FakerJsAdapter

Wraps @faker-js/faker for greater word variety. Requires @faker-js/faker as an optional peer dependency.

import { FakerJsAdapter } from 'malarky';
import { faker } from '@faker-js/faker';

const generator = new TextGenerator({
  fakerAdapter: new FakerJsAdapter(faker),
});

See Guides > Faker Integration for details.