@relyio/sdk 0.12.0 → 0.14.0

package/dist/markdown/index.d.cts

@@ -0,0 +1,111 @@
+import { R as RichTextFieldBlockType, a as RichTextFieldBlock, b as RichTextValue, c as RichTextShapeValue, d as RichTextEntryLinkMark, A as AnyRichTextEntryLink } from '../rich-text.d-BWc-5gX1.cjs';
+
+/**
+ * RelyIO Markdown — or any CommonMark with GitHub's tables, task lists and strikethrough — as the
+ * rich-text tree (REL-1809): the one parser behind the SDK's import, the Studio's paste and the
+ * built-in agents' writes.
+ *
+ * Markdown is read by micromark with the GFM and directive extensions, and the mdast tree it builds
+ * is walked into the tree. Nothing is dropped without a word: what the tree cannot hold — HTML, an
+ * image, a footnote, a link's title, a list mixing tasks and plain items, a label on a declared node
+ * — is **unplaced**, named with its line, its column and its source. {@link richTextFromMarkdown}
+ * refuses Markdown holding any; {@link readRichTextMarkdown} returns them beside the tree it read
+ * with each one's nearest reading in place — the source text itself, where nothing nearer exists —
+ * which is what a paste keeps.
+ *
+ * The parser reads no schema: a directive of a name the tree does not use is a declared node of
+ * that `_type`, and whether the field declares it is the write's to say, as for any tree.
+ */
+
+/** The tree a Markdown document reads as: its declared nodes of any `_type`, its links to entries. */
+type MarkdownTree = RichTextValue<RichTextShapeValue, RichTextShapeValue, RichTextEntryLinkMark>;
+/** Something the tree cannot hold, where it stands in the Markdown and what it says there. */
+interface UnplacedMarkdown {
+    /** What it is, as a reader would say it: `HTML`, `an image`, `a link's title`. */
+    readonly construct: string;
+    /** 1-based. */
+    readonly line: number;
+    /** 1-based. */
+    readonly column: number;
+    /** Its Markdown, as written. */
+    readonly source: string;
+}
+interface RichTextMarkdownReadOptions {
+    /**
+     * Makes each node's key, given the keys taken so far: a first-party caller passes
+     * `@relyio/schema`'s `mintItemKey`. The default makes keys of the same form.
+     */
+    readonly mint?: (taken: ReadonlySet<string>) => string;
+    /**
+     * Whether an entry link may name an entry a create batch has not made yet by its alias, written
+     * as the batch writes one anywhere — `{ "$alias": "jane" }` — in the directive's JSON form:
+     * `:entryLink[Jane]{to:='{"$alias":"jane"}'}` (REL-2112). The link keeps that object as its `to`
+     * for the batch to replace with the entry's uid before anything is written; nothing else takes a
+     * tree holding one. Off by default: an import or a paste names entries by uid.
+     */
+    readonly entryLinkAliases?: boolean;
+}
+/** A reading: the tree, and what it could not place — each in the tree as its nearest reading. */
+interface RichTextMarkdownRead<V> {
+    readonly value: V;
+    readonly unplaced: readonly UnplacedMarkdown[];
+}
+/** Markdown holding what the tree cannot, refused: each unplaced construct, named. */
+declare class RichTextMarkdownImportError extends Error {
+    readonly unplaced: readonly UnplacedMarkdown[];
+    constructor(unplaced: readonly UnplacedMarkdown[]);
+}
+/**
+ * Markdown as the rich-text tree, every node keyed.
+ *
+ * @throws {RichTextMarkdownImportError} when the Markdown holds anything the tree cannot, naming
+ *   each — nothing is dropped.
+ */
+declare function richTextFromMarkdown(markdown: string, options?: RichTextMarkdownReadOptions): MarkdownTree;
+/** Markdown as the rich-text tree, and what it could not place, each in the tree as its nearest reading. */
+declare function readRichTextMarkdown(markdown: string, options?: RichTextMarkdownReadOptions): RichTextMarkdownRead<MarkdownTree>;
+/**
+ * Markdown holding exactly one `table` or `code` field's value (REL-1806): a table — GitHub's or
+ * `:::table` — or a code group, `:::codeGroup` or one fenced block, which is a group of one tab.
+ *
+ * @throws {RichTextMarkdownImportError} when it holds anything else, or anything the tree cannot.
+ */
+declare function richTextFieldBlockFromMarkdown<T extends RichTextFieldBlockType>(markdown: string, type: T, options?: RichTextMarkdownReadOptions): RichTextFieldBlock<T>;
+/** {@link richTextFieldBlockFromMarkdown}'s reading, `null` when the Markdown is not exactly one. */
+declare function readRichTextFieldBlockMarkdown<T extends RichTextFieldBlockType>(markdown: string, type: T, options?: RichTextMarkdownReadOptions): RichTextMarkdownRead<RichTextFieldBlock<T> | null>;
+
+/**
+ * The rich-text tree as RelyIO Markdown (REL-1809): the form that reads back as the same tree, keys
+ * aside. CommonMark, GitHub's tables, task lists and strikethrough, and directives for what neither
+ * has — the syntax is `devtools/docs/guide/schema/field-types/rich-text-markdown.md`'s.
+ *
+ * The tree is turned into an mdast tree and written by `mdast-util-to-markdown` with the GFM and
+ * directive extensions: its escaping is written as the inverse of the micromark parser this
+ * package reads with, so a character that would read back as syntax is escaped by the same grammar
+ * that would have read it. Three handlers are this package's own, each for a place the library would
+ * lose something: a run's line ending (written as a reference, so it is not a soft break), a line
+ * break where a line ending cannot stand (`:lineBreak{}`), and a code block's attributes.
+ *
+ * What the tree holds that RelyIO Markdown cannot name is refused, naming where — never dropped: a
+ * declared node whose `_type` is no directive name, a mark this version does not know.
+ */
+
+/** A tree, with whatever its field declares: what {@link richTextToRelyIOMarkdown} writes. */
+type RichTextMarkdownValue = RichTextValue<RichTextShapeValue, RichTextShapeValue, AnyRichTextEntryLink> | RichTextFieldBlock;
+/** A value RelyIO Markdown cannot say, named by where it stands in the tree. */
+declare class RichTextMarkdownExportError extends Error {
+    readonly at: string;
+    readonly problem: string;
+    constructor(at: string, problem: string);
+}
+/**
+ * A rich-text tree — or a `table` or `code` field's value, the one built-in it is — as RelyIO
+ * Markdown, ending in a newline; `''` for an empty tree. `richTextFromMarkdown` reads it back as the
+ * same tree, keys aside. A read whose include paths expanded an entry link or a declared node's
+ * reference is written with the entry's id, as the value is stored.
+ *
+ * @throws {RichTextMarkdownExportError} naming a node RelyIO Markdown cannot say.
+ */
+declare function richTextToRelyIOMarkdown(value: RichTextMarkdownValue): string;
+
+export { type MarkdownTree, RichTextMarkdownExportError, RichTextMarkdownImportError, type RichTextMarkdownRead, type RichTextMarkdownReadOptions, type RichTextMarkdownValue, type UnplacedMarkdown, readRichTextFieldBlockMarkdown, readRichTextMarkdown, richTextFieldBlockFromMarkdown, richTextFromMarkdown, richTextToRelyIOMarkdown };

package/dist/markdown/index.d.ts

@@ -0,0 +1,111 @@
+import { R as RichTextFieldBlockType, a as RichTextFieldBlock, b as RichTextValue, c as RichTextShapeValue, d as RichTextEntryLinkMark, A as AnyRichTextEntryLink } from '../rich-text.d-BWc-5gX1.js';
+
+/**
+ * RelyIO Markdown — or any CommonMark with GitHub's tables, task lists and strikethrough — as the
+ * rich-text tree (REL-1809): the one parser behind the SDK's import, the Studio's paste and the
+ * built-in agents' writes.
+ *
+ * Markdown is read by micromark with the GFM and directive extensions, and the mdast tree it builds
+ * is walked into the tree. Nothing is dropped without a word: what the tree cannot hold — HTML, an
+ * image, a footnote, a link's title, a list mixing tasks and plain items, a label on a declared node
+ * — is **unplaced**, named with its line, its column and its source. {@link richTextFromMarkdown}
+ * refuses Markdown holding any; {@link readRichTextMarkdown} returns them beside the tree it read
+ * with each one's nearest reading in place — the source text itself, where nothing nearer exists —
+ * which is what a paste keeps.
+ *
+ * The parser reads no schema: a directive of a name the tree does not use is a declared node of
+ * that `_type`, and whether the field declares it is the write's to say, as for any tree.
+ */
+
+/** The tree a Markdown document reads as: its declared nodes of any `_type`, its links to entries. */
+type MarkdownTree = RichTextValue<RichTextShapeValue, RichTextShapeValue, RichTextEntryLinkMark>;
+/** Something the tree cannot hold, where it stands in the Markdown and what it says there. */
+interface UnplacedMarkdown {
+    /** What it is, as a reader would say it: `HTML`, `an image`, `a link's title`. */
+    readonly construct: string;
+    /** 1-based. */
+    readonly line: number;
+    /** 1-based. */
+    readonly column: number;
+    /** Its Markdown, as written. */
+    readonly source: string;
+}
+interface RichTextMarkdownReadOptions {
+    /**
+     * Makes each node's key, given the keys taken so far: a first-party caller passes
+     * `@relyio/schema`'s `mintItemKey`. The default makes keys of the same form.
+     */
+    readonly mint?: (taken: ReadonlySet<string>) => string;
+    /**
+     * Whether an entry link may name an entry a create batch has not made yet by its alias, written
+     * as the batch writes one anywhere — `{ "$alias": "jane" }` — in the directive's JSON form:
+     * `:entryLink[Jane]{to:='{"$alias":"jane"}'}` (REL-2112). The link keeps that object as its `to`
+     * for the batch to replace with the entry's uid before anything is written; nothing else takes a
+     * tree holding one. Off by default: an import or a paste names entries by uid.
+     */
+    readonly entryLinkAliases?: boolean;
+}
+/** A reading: the tree, and what it could not place — each in the tree as its nearest reading. */
+interface RichTextMarkdownRead<V> {
+    readonly value: V;
+    readonly unplaced: readonly UnplacedMarkdown[];
+}
+/** Markdown holding what the tree cannot, refused: each unplaced construct, named. */
+declare class RichTextMarkdownImportError extends Error {
+    readonly unplaced: readonly UnplacedMarkdown[];
+    constructor(unplaced: readonly UnplacedMarkdown[]);
+}
+/**
+ * Markdown as the rich-text tree, every node keyed.
+ *
+ * @throws {RichTextMarkdownImportError} when the Markdown holds anything the tree cannot, naming
+ *   each — nothing is dropped.
+ */
+declare function richTextFromMarkdown(markdown: string, options?: RichTextMarkdownReadOptions): MarkdownTree;
+/** Markdown as the rich-text tree, and what it could not place, each in the tree as its nearest reading. */
+declare function readRichTextMarkdown(markdown: string, options?: RichTextMarkdownReadOptions): RichTextMarkdownRead<MarkdownTree>;
+/**
+ * Markdown holding exactly one `table` or `code` field's value (REL-1806): a table — GitHub's or
+ * `:::table` — or a code group, `:::codeGroup` or one fenced block, which is a group of one tab.
+ *
+ * @throws {RichTextMarkdownImportError} when it holds anything else, or anything the tree cannot.
+ */
+declare function richTextFieldBlockFromMarkdown<T extends RichTextFieldBlockType>(markdown: string, type: T, options?: RichTextMarkdownReadOptions): RichTextFieldBlock<T>;
+/** {@link richTextFieldBlockFromMarkdown}'s reading, `null` when the Markdown is not exactly one. */
+declare function readRichTextFieldBlockMarkdown<T extends RichTextFieldBlockType>(markdown: string, type: T, options?: RichTextMarkdownReadOptions): RichTextMarkdownRead<RichTextFieldBlock<T> | null>;
+
+/**
+ * The rich-text tree as RelyIO Markdown (REL-1809): the form that reads back as the same tree, keys
+ * aside. CommonMark, GitHub's tables, task lists and strikethrough, and directives for what neither
+ * has — the syntax is `devtools/docs/guide/schema/field-types/rich-text-markdown.md`'s.
+ *
+ * The tree is turned into an mdast tree and written by `mdast-util-to-markdown` with the GFM and
+ * directive extensions: its escaping is written as the inverse of the micromark parser this
+ * package reads with, so a character that would read back as syntax is escaped by the same grammar
+ * that would have read it. Three handlers are this package's own, each for a place the library would
+ * lose something: a run's line ending (written as a reference, so it is not a soft break), a line
+ * break where a line ending cannot stand (`:lineBreak{}`), and a code block's attributes.
+ *
+ * What the tree holds that RelyIO Markdown cannot name is refused, naming where — never dropped: a
+ * declared node whose `_type` is no directive name, a mark this version does not know.
+ */
+
+/** A tree, with whatever its field declares: what {@link richTextToRelyIOMarkdown} writes. */
+type RichTextMarkdownValue = RichTextValue<RichTextShapeValue, RichTextShapeValue, AnyRichTextEntryLink> | RichTextFieldBlock;
+/** A value RelyIO Markdown cannot say, named by where it stands in the tree. */
+declare class RichTextMarkdownExportError extends Error {
+    readonly at: string;
+    readonly problem: string;
+    constructor(at: string, problem: string);
+}
+/**
+ * A rich-text tree — or a `table` or `code` field's value, the one built-in it is — as RelyIO
+ * Markdown, ending in a newline; `''` for an empty tree. `richTextFromMarkdown` reads it back as the
+ * same tree, keys aside. A read whose include paths expanded an entry link or a declared node's
+ * reference is written with the entry's id, as the value is stored.
+ *
+ * @throws {RichTextMarkdownExportError} naming a node RelyIO Markdown cannot say.
+ */
+declare function richTextToRelyIOMarkdown(value: RichTextMarkdownValue): string;
+
+export { type MarkdownTree, RichTextMarkdownExportError, RichTextMarkdownImportError, type RichTextMarkdownRead, type RichTextMarkdownReadOptions, type RichTextMarkdownValue, type UnplacedMarkdown, readRichTextFieldBlockMarkdown, readRichTextMarkdown, richTextFieldBlockFromMarkdown, richTextFromMarkdown, richTextToRelyIOMarkdown };