@proseql/core 0.1.0

package/dist/serializers/codecs/prose.d.ts

@@ -0,0 +1,419 @@
+import type { FormatCodec } from "../format-codec.js";
+/**
+ * A segment in a compiled prose template.
+ * Either a literal text segment or a field placeholder.
+ */
+export type ProseSegment = {
+    readonly type: "literal";
+    readonly text: string;
+} | {
+    readonly type: "field";
+    readonly name: string;
+};
+/**
+ * A compiled template ready for encoding/decoding.
+ * Contains the ordered list of segments and extracted field names.
+ */
+export interface CompiledTemplate {
+    readonly segments: ReadonlyArray<ProseSegment>;
+    readonly fields: ReadonlyArray<string>;
+}
+/**
+ * Options for creating a prose codec.
+ */
+export interface ProseCodecOptions {
+    /** The headline template with {fieldName} placeholders */
+    readonly template: string;
+    /** Optional overflow templates for additional fields on indented lines */
+    readonly overflow?: ReadonlyArray<string>;
+}
+/**
+ * Compiles a template string into an ordered list of segments.
+ * Parses `{fieldName}` placeholders and literal text into segments.
+ *
+ * @param template - The template string with {fieldName} placeholders
+ * @returns A CompiledTemplate with segments and field names
+ *
+ * @example
+ * ```typescript
+ * const compiled = compileTemplate('#{id} "{title}" by {author}')
+ * // compiled.segments = [
+ * //   { type: "literal", text: "#" },
+ * //   { type: "field", name: "id" },
+ * //   { type: "literal", text: ' "' },
+ * //   { type: "field", name: "title" },
+ * //   { type: "literal", text: '" by ' },
+ * //   { type: "field", name: "author" },
+ * // ]
+ * // compiled.fields = ["id", "title", "author"]
+ * ```
+ */
+export declare const compileTemplate: (template: string) => CompiledTemplate;
+/**
+ * Compiles an array of overflow template strings into CompiledTemplates.
+ * Each overflow template follows the same {fieldName} placeholder syntax as the headline template.
+ *
+ * @param overflow - Optional array of overflow template strings
+ * @returns An array of CompiledTemplate objects, or empty array if no overflow templates
+ *
+ * @example
+ * ```typescript
+ * const compiled = compileOverflowTemplates(['tagged {tags}', '~ {description}'])
+ * // compiled[0].segments = [
+ * //   { type: "literal", text: "tagged " },
+ * //   { type: "field", name: "tags" },
+ * // ]
+ * // compiled[0].fields = ["tags"]
+ * // compiled[1].segments = [
+ * //   { type: "literal", text: "~ " },
+ * //   { type: "field", name: "description" },
+ * // ]
+ * // compiled[1].fields = ["description"]
+ * ```
+ */
+export declare const compileOverflowTemplates: (overflow: ReadonlyArray<string> | undefined) => ReadonlyArray<CompiledTemplate>;
+/**
+ * Serializes a value to its prose format string representation.
+ *
+ * Type mapping:
+ * - null/undefined → `~`
+ * - boolean → `true` / `false`
+ * - number → digit characters (e.g., `42`, `-3.14`)
+ * - array → `[a, b, c]` with element quoting for `,` and `]`
+ * - string → bare text (quoting for delimiters handled by encodeHeadline)
+ *
+ * @param value - The value to serialize
+ * @returns The serialized string representation
+ *
+ * @example
+ * ```typescript
+ * serializeValue(42)           // "42"
+ * serializeValue(true)         // "true"
+ * serializeValue(null)         // "~"
+ * serializeValue("hello")      // "hello"
+ * serializeValue(["a", "b"])   // "[a, b]"
+ * ```
+ */
+export declare const serializeValue: (value: unknown) => string;
+/**
+ * Deserializes a prose format string back to its typed value.
+ * Uses heuristic type detection:
+ * - Numbers: matches `/^-?\d+(\.\d+)?$/`
+ * - Booleans: exact match `true` or `false`
+ * - Null: exact match `~`
+ * - Arrays: starts with `[`, ends with `]`
+ * - Strings: default (anything not matching above)
+ *
+ * @param text - The serialized string to deserialize
+ * @returns The deserialized value with its inferred type
+ *
+ * @example
+ * ```typescript
+ * deserializeValue("42")           // 42 (number)
+ * deserializeValue("-3.14")        // -3.14 (number)
+ * deserializeValue("true")         // true (boolean)
+ * deserializeValue("false")        // false (boolean)
+ * deserializeValue("~")            // null
+ * deserializeValue("[a, b, c]")    // ["a", "b", "c"] (array)
+ * deserializeValue("hello")        // "hello" (string)
+ * ```
+ */
+export declare const deserializeValue: (text: string) => unknown;
+/**
+ * Encodes a record into a headline string using a compiled template.
+ * Substitutes field values into the template, emitting literals verbatim.
+ * For non-last fields, if the serialized value contains the next literal
+ * delimiter, the value is quoted to prevent parsing ambiguity.
+ *
+ * @param record - The record object with field values
+ * @param template - The compiled template with segments and fields
+ * @returns The encoded headline string
+ *
+ * @example
+ * ```typescript
+ * const template = compileTemplate('#{id} "{title}" by {author}')
+ * const record = { id: "1", title: "Dune", author: "Frank Herbert" }
+ * encodeHeadline(record, template)
+ * // → '#1 "Dune" by Frank Herbert'
+ *
+ * // When value contains the next delimiter:
+ * const record2 = { id: "1", title: 'Say "hello"', author: "Test" }
+ * encodeHeadline(record2, template)
+ * // → '#1 "Say \"hello\"" by Test'
+ * ```
+ */
+export declare const encodeHeadline: (record: Record<string, unknown>, template: CompiledTemplate) => string;
+/**
+ * Decodes a headline string back to a record using a compiled template.
+ * Performs a left-to-right scan matching literals and capturing field text between them.
+ * Returns null if the line doesn't match the template structure.
+ *
+ * @param line - The headline string to decode
+ * @param template - The compiled template with segments and fields
+ * @returns The decoded record object, or null if the line doesn't match
+ *
+ * @example
+ * ```typescript
+ * const template = compileTemplate('#{id} "{title}" by {author}')
+ * decodeHeadline('#1 "Dune" by Frank Herbert', template)
+ * // → { id: "1", title: "Dune", author: "Frank Herbert" }
+ *
+ * decodeHeadline('This does not match', template)
+ * // → null
+ * ```
+ */
+export declare const decodeHeadline: (line: string, template: CompiledTemplate) => Record<string, unknown> | null;
+/**
+ * Encodes overflow fields for a record as indented lines.
+ * For each overflow template, if the record has a non-null/non-undefined value
+ * for the field in that template, emits an indented line using the template.
+ * Overflow fields with null or undefined values are omitted.
+ *
+ * For multi-line string values (containing newlines), the first line is encoded
+ * on the template line, and subsequent lines are emitted as continuation lines
+ * with deeper indentation.
+ *
+ * @param record - The record object with field values
+ * @param overflowTemplates - Array of compiled overflow templates
+ * @returns Array of indented overflow line strings
+ *
+ * @example
+ * ```typescript
+ * const templates = compileOverflowTemplates(['tagged {tags}', '~ {description}'])
+ * const record = { id: "1", title: "Dune", tags: ["classic"], description: null }
+ * encodeOverflowLines(record, templates)
+ * // → ['  tagged [classic]']
+ * // Note: description is null, so its overflow line is omitted
+ *
+ * // Multi-line value:
+ * const record2 = { id: "1", description: "Line one\nLine two" }
+ * encodeOverflowLines(record2, compileOverflowTemplates(['~ {description}']))
+ * // → ['  ~ Line one', '    Line two']
+ * ```
+ */
+export declare const encodeOverflowLines: (record: Record<string, unknown>, overflowTemplates: ReadonlyArray<CompiledTemplate>) => ReadonlyArray<string>;
+/**
+ * Result of decoding overflow lines for a record.
+ */
+export interface DecodeOverflowResult {
+    /** The decoded field values from overflow lines */
+    readonly fields: Record<string, unknown>;
+    /** Number of lines consumed (including continuation lines) */
+    readonly linesConsumed: number;
+}
+/**
+ * Decodes overflow lines for a record using the configured overflow templates.
+ * Collects indented lines belonging to the record, tries each overflow template
+ * in order, skips on non-match, and captures field values on match.
+ *
+ * For each indented line:
+ * 1. Try matching against each overflow template (in order)
+ * 2. If a template matches, capture the field values and move to next line
+ * 3. If no template matches, check if it's a continuation line (deeper indentation)
+ * 4. Continuation lines are appended to the previous field's value with newline
+ *
+ * @param lines - Array of indented lines (already collected for this record)
+ * @param overflowTemplates - Array of compiled overflow templates
+ * @param baseIndent - The expected indentation level for overflow lines (default: 2)
+ * @returns The decoded field values and number of lines consumed
+ *
+ * @example
+ * ```typescript
+ * const templates = compileOverflowTemplates(['tagged {tags}', '~ {description}'])
+ * const lines = ['  tagged [sci-fi]', '  ~ A classic novel']
+ * const result = decodeOverflowLines(lines, templates)
+ * // → { fields: { tags: ['sci-fi'], description: 'A classic novel' }, linesConsumed: 2 }
+ * ```
+ */
+export declare const decodeOverflowLines: (lines: ReadonlyArray<string>, overflowTemplates: ReadonlyArray<CompiledTemplate>, baseIndent?: number) => DecodeOverflowResult;
+/**
+ * Result of scanning for the @prose directive in a document.
+ */
+export interface ScanDirectiveResult {
+    /** Index of the last line before the directive (or -1 if no preamble) */
+    readonly preambleEnd: number;
+    /** Index of the line containing the @prose directive */
+    readonly directiveStart: number;
+}
+/**
+ * Scans a document for the @prose directive.
+ * The directive is a line starting with `@prose ` (note the trailing space).
+ *
+ * Rules:
+ * - Exactly one @prose directive must exist in the file
+ * - If no directive is found, throws an error
+ * - If multiple directives are found, throws an error
+ * - All lines before the directive are preamble
+ *
+ * @param lines - Array of lines from the document
+ * @returns The position information for preamble and directive
+ * @throws Error if no directive found or multiple directives found
+ *
+ * @example
+ * ```typescript
+ * const lines = ['# My Books', '', '@prose #{id} {title}', '#1 Dune']
+ * const result = scanDirective(lines)
+ * // → { preambleEnd: 1, directiveStart: 2 }
+ *
+ * const linesNoPreable = ['@prose #{id} {title}', '#1 Dune']
+ * const result2 = scanDirective(linesNoPreable)
+ * // → { preambleEnd: -1, directiveStart: 0 }
+ * ```
+ */
+export declare const scanDirective: (lines: ReadonlyArray<string>) => ScanDirectiveResult;
+/**
+ * Result of parsing a directive block.
+ */
+export interface DirectiveBlock {
+    /** The headline template (content after @prose) */
+    readonly headlineTemplate: string;
+    /** Overflow templates (indented lines immediately after @prose) */
+    readonly overflowTemplates: ReadonlyArray<string>;
+    /** Index of the first line after the directive block (body start) */
+    readonly bodyStart: number;
+}
+/**
+ * Parses a directive block from the document.
+ * Extracts the headline template from the @prose line and collects
+ * any indented overflow templates that immediately follow.
+ *
+ * The directive block structure:
+ * ```
+ * @prose #{id} "{title}" by {author}   ← headline template
+ *   tagged {tags}                       ← overflow template 1
+ *   ~ {description}                     ← overflow template 2
+ *                                       ← blank line or non-indented = end of block
+ * ```
+ *
+ * Overflow templates are lines that:
+ * - Immediately follow the @prose line (no blank lines between)
+ * - Are indented (start with whitespace)
+ *
+ * @param lines - Array of lines from the document
+ * @param directiveStart - Index of the @prose directive line
+ * @returns The parsed directive block with template strings and body start index
+ *
+ * @example
+ * ```typescript
+ * const lines = [
+ *   '@prose #{id} "{title}"',
+ *   '  tagged {tags}',
+ *   '  ~ {description}',
+ *   '',
+ *   '#1 "Dune"',
+ * ]
+ * const result = parseDirectiveBlock(lines, 0)
+ * // → {
+ * //   headlineTemplate: '#{id} "{title}"',
+ * //   overflowTemplates: ['tagged {tags}', '~ {description}'],
+ * //   bodyStart: 3
+ * // }
+ * ```
+ */
+export declare const parseDirectiveBlock: (lines: ReadonlyArray<string>, directiveStart: number) => DirectiveBlock;
+/**
+ * Represents a parsed entry from the body section of a prose document.
+ * Can be either a record (matched the headline template) or pass-through text.
+ */
+export type ProseEntry = {
+    readonly type: "record";
+    /** The decoded headline fields */
+    readonly fields: Record<string, unknown>;
+    /** The raw headline line */
+    readonly headline: string;
+    /** Indented overflow lines belonging to this record */
+    readonly overflowLines: ReadonlyArray<string>;
+} | {
+    readonly type: "passthrough";
+    /** Raw text lines that didn't match the template */
+    readonly lines: ReadonlyArray<string>;
+};
+/**
+ * Result of parsing the body section of a prose document.
+ */
+export interface ParseBodyResult {
+    /** The parsed entries (interleaved records and pass-through text) */
+    readonly entries: ReadonlyArray<ProseEntry>;
+}
+/**
+ * Parses the body section of a prose document.
+ * Iterates lines after the directive block and classifies each as:
+ * - Record headline (matches the compiled template)
+ * - Indented overflow/continuation (part of the current record)
+ * - Pass-through text (doesn't match, preserved verbatim)
+ *
+ * @param lines - Array of lines from the document
+ * @param bodyStart - Index of the first line of the body (after directive block)
+ * @param headlineTemplate - The compiled headline template
+ * @returns The parsed body with interleaved records and pass-through text
+ *
+ * @example
+ * ```typescript
+ * const lines = [
+ *   '@prose #{id} "{title}"',
+ *   '',
+ *   '## Science Fiction',
+ *   '#1 "Dune"',
+ *   '  tagged [classic]',
+ *   '#2 "Neuromancer"',
+ *   '',
+ *   '## Fantasy',
+ *   '#3 "The Hobbit"',
+ * ]
+ * const template = compileTemplate('#{id} "{title}"')
+ * const result = parseBody(lines, 1, template)
+ * // → {
+ * //   entries: [
+ * //     { type: "passthrough", lines: ["", "## Science Fiction"] },
+ * //     { type: "record", fields: { id: "1", title: "Dune" }, headline: '#1 "Dune"', overflowLines: ["  tagged [classic]"] },
+ * //     { type: "record", fields: { id: "2", title: "Neuromancer" }, headline: '#2 "Neuromancer"', overflowLines: [] },
+ * //     { type: "passthrough", lines: ["", "## Fantasy"] },
+ * //     { type: "record", fields: { id: "3", title: "The Hobbit" }, headline: '#3 "The Hobbit"', overflowLines: [] },
+ * //   ]
+ * // }
+ * ```
+ */
+export declare const parseBody: (lines: ReadonlyArray<string>, bodyStart: number, headlineTemplate: CompiledTemplate) => ParseBodyResult;
+/**
+ * Creates a prose format codec for human-readable, template-driven serialization.
+ *
+ * The prose format uses a `@prose` directive to define a sentence-like pattern
+ * mapping field names to positions within literal delimiter text. Records follow
+ * this pattern, producing human-readable lines.
+ *
+ * Templates use `{fieldName}` placeholders mixed with literal text:
+ * ```
+ * @prose #{id} "{title}" by {authorId} ({year}) — {genre}
+ *   tagged {tags}
+ *   ~ {description}
+ * ```
+ *
+ * The codec compiles templates at construction time and returns a standard
+ * FormatCodec with encode/decode functions.
+ *
+ * @param options - Codec configuration with headline and overflow templates
+ * @param options.template - The headline template with {fieldName} placeholders
+ * @param options.overflow - Optional array of overflow templates for additional fields
+ * @returns A FormatCodec for prose serialization
+ *
+ * @example
+ * ```typescript
+ * const codec = proseCodec({
+ *   template: '#{id} "{title}" by {author}',
+ *   overflow: ['tagged {tags}', '~ {description}'],
+ * })
+ *
+ * const layer = makeSerializerLayer([codec])
+ *
+ * // Encoded output:
+ * // @prose #{id} "{title}" by {author}
+ * //   tagged {tags}
+ * //   ~ {description}
+ * //
+ * // #1 "Dune" by Frank Herbert
+ * //   tagged [sci-fi, classic]
+ * //   ~ A masterpiece of science fiction
+ * ```
+ */
+export declare const proseCodec: (options: ProseCodecOptions) => FormatCodec;
+//# sourceMappingURL=prose.d.ts.map

package/dist/serializers/codecs/prose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose.d.ts","sourceRoot":"","sources":["../../../src/serializers/codecs/prose.ts"],"names":[],"mappings":"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"}