prose-writer 0.1.0 → 0.1.2

package/README.md

@@ -2,6 +2,33 @@
 
 A zero-dependency, chainable TypeScript library for building formatted text and markdown strings. Perfect for constructing LLM prompts, generating documentation, or any scenario where you need to programmatically build structured text.
 
+## In one sentence
+
+Prose Writer is a fluent builder for producing markdown-friendly strings without template literal sprawl.
+
+## When to use it
+
+- You need readable, composable prompt or document builders in code
+- You want conditionals, loops, and reusable pieces without `.map().join()` or manual concatenation
+- You need safe handling of untrusted input or structured output sections (JSON/YAML)
+
+## How it works (3 steps)
+
+1. `write()` creates a builder (optionally with initial text).
+2. Chain block helpers like `.section()`, `.list()`, `.tag()`, `.codeblock()`, `.json()`.
+3. Call `.toString()` or `String(writer)` to get the final text.
+
+```typescript
+import { write } from 'prose-writer';
+
+const prompt = write('You are a helpful assistant.')
+  .section('Guidelines', (w) => w.list('Be concise', 'Cite sources'))
+  .tag('input', userText)
+  .toString();
+```
+
+Each `write()` call ends with a newline, so chained calls become separate paragraphs (a blank line between). To keep content on the same line, pass multiple strings to a single `write()` call. Most block helpers add blank lines around themselves so the output reads like markdown paragraphs. Use `write()` with no args to insert an extra blank line.
+
 ## Why Prose Writer?
 
 Building prompts for LLMs in code is _painful_. You end up with wild stuff like this.
@@ -23,7 +50,27 @@ ${context}
 
 Template literals become unreadable. String concatenation is worse. And when you need conditionals, variables, or reusable pieces? Good luck.
 
-**prose-writer** fixes this:
+Compared to concatenating arrays of strings, Prose Writer keeps structure and spacing inside the builder instead of scattering `join()` logic, manual newlines, and nested maps across your code. Compared to giant template strings, it avoids brittle whitespace and makes conditional or reusable sections readable and composable.
+
+Array concatenation version:
+
+```typescript
+const prompt = [
+  `You are a ${role}.`,
+  '',
+  '## Guidelines',
+  ...guidelines.map((g) => `- ${g}`),
+  '',
+  '## Examples',
+  ...examples.map((ex, i) => `### Example ${i + 1}\n${ex}`),
+  '',
+  '<context>',
+  context,
+  '</context>',
+].join('\n');
+```
+
+Prose Writer version:
 
 ```typescript
 const prompt = write(`You are a ${role}.`)
@@ -42,7 +89,6 @@ const prompt = write(`You are a ${role}.`)
 - **Composable** - Build prompts from reusable pieces with `.append()` and `.clone()`
 - **Logical grouping** - Use `.with(builder)` to group related operations
 - **Conditional logic** - Add sections conditionally with `.when(condition, builder)`
-- **Template variables** - Use `{{placeholders}}` and `.fill()` for dynamic content
 - **LLM-optimized** - Built-in `.tag()` for XML delimiters (Claude loves these), `.json()` and `.yaml()` for structured output instructions
 - **Batch operations** - Iterate with `.each()` instead of awkward `.map().join()` chains
 - **Token awareness** - Estimate prompt size with `.tokens()`
@@ -52,7 +98,8 @@ const prompt = write(`You are a ${role}.`)
 ### Real-world example
 
 ```typescript
-import { write, bold, code } from 'prose-writer';
+import { write } from 'prose-writer';
+import { bold, code } from 'prose-writer/markdown';
 
 // Define reusable components
 const codeReviewPersona = write('You are a', bold('senior software engineer.')).write(
@@ -65,6 +112,9 @@ const outputFormat = write('').definitions({
   suggestions: 'Recommended improvements',
 });
 
+const language = 'TypeScript';
+const framework = 'React';
+
 // Build the prompt
 const reviewPrompt = write('')
   .append(codeReviewPersona)
@@ -78,7 +128,8 @@ const reviewPrompt = write('')
   .when(strictMode, (w) => w.write('Be extremely thorough. Miss nothing.'))
   .section('Output Format', (w) => w.append(outputFormat))
   .tag('code', userCode)
-  .fill({ language: 'TypeScript', framework: 'React' });
+  .write('Language:', language)
+  .write('Framework:', framework);
 ```
 
 Stop fighting with template strings. Start writing prompts that are readable, maintainable, and composable.
@@ -96,10 +147,47 @@ npm install prose-writer
 pnpm add prose-writer
 ```
 
+## Exports
+
+Core:
+
+```typescript
+import { write, ProseWriter } from 'prose-writer';
+```
+
+Markdown utilities:
+
+```typescript
+import { bold, italic, code, strike, link, image } from 'prose-writer/markdown';
+```
+
+Validation helpers:
+
+```typescript
+import {
+  createJsonSchemaValidator,
+  createYamlParserAdapter,
+  ValidationError,
+} from 'prose-writer/validation';
+```
+
+Schema types:
+
+```typescript
+import type { SchemaEmbedOptions } from 'prose-writer/schema';
+```
+
+Safe writer:
+
+```typescript
+import { write } from 'prose-writer/safe';
+```
+
 ## Quick Start
 
 ```typescript
-import { write, bold } from 'prose-writer';
+import { write } from 'prose-writer';
+import { bold } from 'prose-writer/markdown';
 
 const prompt = write('You are a', bold('helpful assistant.'))
   .write('Please help the user with their request.')
@@ -122,7 +210,8 @@ Please help the user with their request.
 Creates a new `ProseWriter` instance. Multiple arguments are joined with a space, and a newline is added at the end. Can be called with zero arguments to add a blank line between other `write()` calls.
 
 ```typescript
-import { write, bold, code } from 'prose-writer';
+import { write } from 'prose-writer';
+import { bold, code } from 'prose-writer/markdown';
 
 const text = write('Hello', bold('World')).toString();
 ```
@@ -133,6 +222,26 @@ Output:
 Hello **World**
 ```
 
+### `write.safe(...content: string[])`
+
+Creates a `ProseWriter` that escapes untrusted input. Safe mode:
+
+- Escapes Markdown punctuation and line-leading markers (lists, headings, blockquotes)
+- Escapes XML-sensitive characters (`&`, `<`, `>`) in text and tags
+- Sanitizes link text + destinations
+- Wraps inline code with a backtick fence that can't be broken by user input
+
+Use this when inserting user-generated content. To intentionally include raw Markdown, pass a `ProseWriter` instance or call `.raw()` to bypass escaping.
+You can also import a safe-first writer: `import { write } from 'prose-writer/safe'`.
+
+```typescript
+const prompt = write
+  .safe('User input:', userInput)
+  .tag('context', userInput)
+  .link('Source', userUrl)
+  .toString();
+```
+
 You can also start a chain using `write.with()` if you want to use the builder pattern immediately:
 
 ```typescript
@@ -150,20 +259,21 @@ Hello **World**
 ```
 
 ```typescript
-const multiLine = write('First line').write('Second line').toString();
+const multiParagraph = write('First line').write('Second line').toString();
 ```
 
 Output:
 
 ```markdown
 First line
+
 Second line
 ```
 
-Adding a blank line between paragraphs:
+Adding an extra blank line between paragraphs:
 
 ```typescript
-const multiParagraph = write('Paragraph 1').write().write('Paragraph 2').toString();
+const spacedParagraphs = write('Paragraph 1').write().write('Paragraph 2').toString();
 ```
 
 Output:
@@ -176,7 +286,7 @@ Paragraph 2
 
 ### `.write(...content: string[])`
 
-Appends content to the prose. Multiple arguments are joined with a space, and a newline is added at the end. Returns `this` for chaining.
+Appends content to the prose. Multiple arguments are joined with a space, and a newline is added at the end. Each chained call starts a new paragraph (blank line), so use a single `write()` call when you want one line.
 
 ```typescript
 write('User:').write('Hello', 'Assistant').toString();
@@ -189,6 +299,18 @@ User:
 Hello Assistant
 ```
 
+Same line by passing multiple strings:
+
+```typescript
+write('User:', 'Hello', 'Assistant').toString();
+```
+
+Output:
+
+```markdown
+User: Hello Assistant
+```
+
 ### Inline Utilities
 
 The following utilities return formatted strings and can be used within `write()` calls or anywhere else.
@@ -202,7 +324,8 @@ The following utilities return formatted strings and can be used within `write()
 - `image(alt: string, url: string)` - `![alt](url)`
 
 ```typescript
-import { write, bold, italic, code, link } from 'prose-writer';
+import { write } from 'prose-writer';
+import { bold, italic, code, link } from 'prose-writer/markdown';
 
 write(
   'Check out',
@@ -218,21 +341,6 @@ write(
 
 Obviously, you can just write regular Markdown here as well.
 
-### `.nextLine()`
-
-Prevents the next block element or `write()` call from adding a paragraph break. Useful for placing content on consecutive lines.
-
-```typescript
-write('Line 1').nextLine().write('Line 2').toString();
-```
-
-Output:
-
-```markdown
-Line 1
-Line 2
-```
-
 ### `.unorderedList(...items: string[] | number[] | boolean[] | ProseWriter[])`
 
 ### `.list(...items: string[] | number[] | boolean[] | ProseWriter[])`
@@ -552,7 +660,7 @@ Section 1
 Section 2
 ```
 
-### `.json(data: unknown)`
+### `.json(data: unknown, options?: ValidationOptions)`
 
 Appends a JSON code block. If the data is not a string, it will be stringified with formatting.
 
@@ -587,6 +695,17 @@ Output:
 ```
 ````
 
+You can pass validation hooks via `options`:
+
+```typescript
+write('').json(data, {
+  schema: outputSchema,
+  validate: ({ format, data, schema }) => {
+    // return { valid: true } or { valid: false, issues: [...] }
+  },
+});
+```
+
 ### `.append(writer: ProseWriter)`
 
 Appends the content from another `ProseWriter` instance. Enables composition of prompts from reusable pieces.
@@ -694,7 +813,8 @@ function.
 // Recommended:
 
 ```typescript
-import { write, code } from 'prose-writer';
+import { write } from 'prose-writer';
+import { code } from 'prose-writer/markdown';
 write('Use the', code('calculateTotal'), 'function.').toString();
 ```
 
@@ -704,21 +824,6 @@ Output:
 Use the `calculateTotal` function.
 ```
 
-### `.fill(variables: Record<string, string>)`
-
-Replaces template variables in the format `{{variableName}}` with provided values. Returns a new `ProseWriter` with the substitutions applied (does not modify the original).
-
-```typescript
-const template = write('Hello, {{name}}! Welcome to {{place}}.');
-const result = template.fill({ name: 'Alice', place: 'Wonderland' }).toString();
-```
-
-Output:
-
-```markdown
-Hello, Alice! Welcome to Wonderland.
-```
-
 ### `.section(name: string, builder: (writer) => void, level?: 1-6)`
 
 Creates a semantic section with a heading and content built by the builder function. The optional `level` parameter defaults to 2.
@@ -815,7 +920,8 @@ information.
 // Recommended:
 
 ```typescript
-import { write, bold } from 'prose-writer';
+import { write } from 'prose-writer';
+import { bold } from 'prose-writer/markdown';
 write('This is', bold('important'), 'information.').toString();
 ```
 
@@ -844,7 +950,8 @@ the following.
 // Recommended:
 
 ```typescript
-import { write, italic } from 'prose-writer';
+import { write } from 'prose-writer';
+import { italic } from 'prose-writer/markdown';
 write('Please', italic('note'), 'the following.').toString();
 ```
 
@@ -893,7 +1000,8 @@ New
 // Recommended:
 
 ```typescript
-import { write, strike } from 'prose-writer';
+import { write } from 'prose-writer';
+import { strike } from 'prose-writer/markdown';
 write('Price:', strike('$100'), '$80').toString();
 ```
 
@@ -949,7 +1057,8 @@ for details.
 // Recommended:
 
 ```typescript
-import { write, link } from 'prose-writer';
+import { write } from 'prose-writer';
+import { link } from 'prose-writer/markdown';
 write('See the', link('documentation', 'https://example.com'), 'for details.').toString();
 ```
 
@@ -959,7 +1068,7 @@ Output:
 See the [documentation](https://example.com) for details.
 ```
 
-### `.yaml(data: unknown)`
+### `.yaml(data: unknown, options?: ValidationOptions)`
 
 Appends a YAML code block. If data is not a string, it will be converted to YAML format.
 
@@ -996,6 +1105,74 @@ Wraps content with custom delimiters. Useful for models that respond to specific
 write('Input:').delimit('###', '###', 'content here').toString();
 ```
 
+### Structured Output Validation
+
+`json()` and `yaml()` accept a `validate` hook. If validation fails, a `ValidationError` is thrown with diagnostic details.
+When validating JSON, string inputs are parsed first and will throw a `ValidationError` if they are invalid JSON. For YAML, you can supply a parser via `parseYaml` to parse strings before validation.
+
+```typescript
+import type { OutputValidator } from 'prose-writer/validation';
+
+const validate: OutputValidator = ({ format, data, schema }) => {
+  if (format !== 'json') return { valid: true };
+  if (!schema) return { valid: true };
+  // Your validation logic here
+  return { valid: true };
+};
+
+write('').json(payload, { schema: outputSchema, validate });
+```
+
+For YAML string inputs, pass a parser adapter:
+
+```typescript
+import { parse as parseYaml } from 'yaml';
+import { createYamlParserAdapter } from 'prose-writer/validation';
+
+write('').yaml(payloadString, {
+  validate,
+  parseYaml: createYamlParserAdapter(parseYaml),
+});
+```
+
+#### JSON Schema via Adapter
+
+`prose-writer` stays zero-deps, but you can plug in Ajv (or any validator) through an adapter.
+
+```typescript
+import Ajv from 'ajv';
+import { createJsonSchemaValidator } from 'prose-writer/validation';
+
+const ajv = new Ajv();
+const validate = createJsonSchemaValidator((schema, data) => {
+  const valid = ajv.validate(schema, data);
+  if (valid) return { valid: true };
+  return {
+    valid: false,
+    issues: (ajv.errors ?? []).map((error) => ({
+      path: error.instancePath || '$',
+      message: error.message ?? 'Invalid value',
+    })),
+  };
+});
+
+write('').json(payload, { schema: outputSchema, validate });
+```
+
+#### Embedding Schemas in Prompts
+
+```typescript
+write('Return JSON that matches this schema:')
+  .schema(outputSchema, { title: 'Output Schema', tag: 'output_schema' })
+  .toString();
+```
+
+Recommended usage:
+
+- Prefer JSON Schema for structured output formats.
+- Store schemas alongside prompt builders and include them in the prompt with `.schema()`.
+- Validate the object you send or receive, not just the stringified output.
+
 ### `.compact()`
 
 Returns a new ProseWriter with consecutive newlines (3+) collapsed to double newlines.
@@ -1080,7 +1257,8 @@ Features:
 Converts the prose to plain text by stripping all markdown formatting.
 
 ```typescript
-import { write, bold } from 'prose-writer';
+import { write } from 'prose-writer';
+import { bold } from 'prose-writer/markdown';
 
 const prose = write('')
   .heading(1, 'Title')
@@ -1111,17 +1289,6 @@ const conclusion = write('').heading(2, 'Conclusion').write('Summary');
 const document = ProseWriter.join(intro, body, conclusion);
 ```
 
-### `ProseWriter.fromTemplate(template: string)`
-
-Static method that creates a ProseWriter from a template string.
-
-```typescript
-const prompt = ProseWriter.fromTemplate('Hello {{name}}, your role is {{role}}.').fill({
-  name: 'Alice',
-  role: 'developer',
-});
-```
-
 ### `.toString()`
 
 Converts the accumulated prose to a string.
@@ -1248,48 +1415,13 @@ const userPrompt = write('Please review the following code:')
   .toString();
 ```
 
-## Prompt Templates and Variations
+## Prompt Variations
 
-Use `fill()` for variable interpolation and `clone()` to create prompt variations:
+Use `clone()` to create variations without mutating the original prompt:
 
 ```typescript
 import { write } from 'prose-writer';
 
-// Create a reusable template
-const promptTemplate = write('You are a {{role}}.')
-  .section('Task', (w) => {
-    w.write('Help the user with {{task}}.');
-  })
-  .section('Guidelines', (w) => {
-    w.list('Be {{style}}', 'Focus on {{focus}}');
-  })
-  .section('Output', (w) => {
-    w.table(
-      ['Format', 'When to use'],
-      [
-        ['Code blocks', 'For code examples'],
-        ['Bullet points', 'For lists of items'],
-        ['Tables', 'For structured data'],
-      ],
-    );
-  });
-
-// Create variations for different use cases
-const codeReviewPrompt = promptTemplate.fill({
-  role: 'senior software engineer',
-  task: 'code review',
-  style: 'thorough and constructive',
-  focus: 'code quality and best practices',
-});
-
-const debuggingPrompt = promptTemplate.fill({
-  role: 'debugging expert',
-  task: 'finding and fixing bugs',
-  style: 'systematic and methodical',
-  focus: 'root cause analysis',
-});
-
-// Or use clone() for structural variations
 const basePrompt = write('You are an AI assistant.').section('Core Guidelines', (w) => {
   w.list('Be helpful', 'Be accurate');
 });

package/dist/index.d.ts

@@ -1 +1 @@
-export { bold, code, image, inline, italic, link, ProseWriter, strike, write, } from './prose-writer';
+export { ProseWriter, write } from './prose-writer';