@graphty/graph-io 0.0.0 → 0.2.0

package/dist/src/registry.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The importer / exporter registry (design sections 8.2 and 8.4): the eight built-in formats
+ * registered by name, `sniff()` over them, and the two conveniences for callers who do not own a
+ * sink: `importGraph()` sniffs the format, creates a builder seeded from the common options
+ * (`directed: true` as a placeholder; the importer sets the real value), imports and freezes;
+ * `exportGraph()` looks the exporter up by name. A caller who owns a builder uses the importer
+ * objects directly (the subpath exports) and this module never touches their sink.
+ */
+import { type FreezeOptions, type FreezeReport, type GraphBuilderOptions, type GraphSnapshot } from "@graphty/graph-format";
+import { type SniffHints, type SniffResult } from "./sniff.js";
+import { type CommonExportOptions, type CommonImportOptions, type GraphExporter, type GraphImporter, type ImportInput, type ImportReport, type LossNote } from "./types.js";
+/** The issue code of an input whose format no registered importer recognises. */
+export declare const UNKNOWN_FORMAT_CODE = "E_UNKNOWN_FORMAT";
+/** The builder options importGraph() accepts beyond the ones the common import options seed. */
+export type BuilderSeed = Omit<GraphBuilderOptions, "directed" | "addMissingNodes" | "duplicateEdges" | "selfLoops" | "weightDtype">;
+/**
+ * The options of importGraph(): the common import options (which also seed the registry's
+ * builder, design section 8.4), the format choice and the hints sniffing uses, the builder and
+ * freeze options, and any format-specific option (`delimiter`, `dialect`, ...) passed through to
+ * the importer unchanged.
+ */
+export interface ImportGraphOptions extends CommonImportOptions {
+    /** The format name, or "auto" (default) to sniff it from the filename, MIME type and content. */
+    readonly format?: string | undefined;
+    /** The file name or path the input came from, a hint for sniffing. */
+    readonly filename?: string | null | undefined;
+    /** The MIME type the input was served as, a hint for sniffing. */
+    readonly mimeType?: string | null | undefined;
+    /** Builder options the common options do not cover (`weighted`, `expectedNodes`, ...). */
+    readonly builder?: BuilderSeed | undefined;
+    /** Options of the freeze that follows the import. */
+    readonly freeze?: FreezeOptions | undefined;
+    /** Format-specific options, passed to the importer as they are. */
+    readonly [formatOption: string]: unknown;
+}
+/** What importGraph() returns (design section 8.4). */
+export interface ImportGraphResult {
+    /** The format the input was read as. */
+    readonly format: string;
+    /** The sniff that chose the importer, or null when the caller named the format. */
+    readonly sniff: SniffResult | null;
+    /** The frozen snapshot. */
+    readonly snapshot: GraphSnapshot;
+    /** The importer's report. */
+    readonly report: ImportReport;
+    /** The freeze report (design section 6.6). */
+    readonly freeze: FreezeReport;
+}
+/** The options of exportGraph(): the common export options plus any format-specific option, passed through. */
+export interface ExportGraphOptions extends CommonExportOptions {
+    /** Format-specific options, passed to the exporter as they are. */
+    readonly [formatOption: string]: unknown;
+}
+/**
+ * A registry of importers and exporters by format name. Registration order is the tie-break
+ * order of sniffing (design section 8.2); the default registry lists the built-in formats in the
+ * order of GRAPH_FORMATS.
+ */
+export declare class FormatRegistry {
+    private readonly importerMap;
+    private readonly exporterMap;
+    /**
+     * Register an importer under its format name, replacing one of the same name in place (the
+     * original registration order is kept).
+     * @param importer - the importer
+     * @returns this registry, for chaining
+     */
+    registerImporter(importer: GraphImporter): this;
+    /**
+     * Register an exporter under its format name, replacing one of the same name.
+     * @param exporter - the exporter
+     * @returns this registry, for chaining
+     */
+    registerExporter(exporter: GraphExporter): this;
+    /**
+     * The importer of a format.
+     * @param format - the format name
+     * @returns the importer; E_UNSUPPORTED when none is registered
+     */
+    importer(format: string): GraphImporter;
+    /**
+     * The exporter of a format.
+     * @param format - the format name
+     * @returns the exporter; E_UNSUPPORTED when none is registered
+     */
+    exporter(format: string): GraphExporter;
+    /**
+     * Whether an importer is registered for a format.
+     * @param format - the format name
+     * @returns true when importer(format) would succeed
+     */
+    hasImporter(format: string): boolean;
+    /**
+     * Whether an exporter is registered for a format.
+     * @param format - the format name
+     * @returns true when exporter(format) would succeed
+     */
+    hasExporter(format: string): boolean;
+    /**
+     * Every registered importer, in registration order.
+     * @returns the importers
+     */
+    importers(): readonly GraphImporter[];
+    /**
+     * Every registered exporter, in registration order.
+     * @returns the exporters
+     */
+    exporters(): readonly GraphExporter[];
+    /**
+     * The names of every format with an importer or an exporter, importers' order first.
+     * @returns the format names, each once
+     */
+    formats(): readonly string[];
+    /**
+     * Rank the registered importers for an input (design section 8.2; the successor of
+     * graphty-element's detectFormat()).
+     * @param hints - the filename, MIME type and / or head of the input
+     * @returns the candidates, best first; empty when nothing matches
+     */
+    sniffAll(hints: SniffHints): readonly SniffResult[];
+    /**
+     * The best importer for an input, or null when no registered importer claims it.
+     * @param hints - the filename, MIME type and / or head of the input
+     * @returns the best candidate, or null
+     */
+    sniff(hints: SniffHints): SniffResult | null;
+    /**
+     * Read an input into a fresh builder and freeze it (design section 8.4: for callers who do not
+     * own a sink). The format is the one named in the options, else sniffed from the filename,
+     * the MIME type and the first bytes of the content; the builder is seeded from the common
+     * options with `directed: true` as a placeholder that the importer overrides from the file.
+     * @param input - the text, bytes, stream or chunks to read
+     * @param options - the format, hints, common and format-specific import options
+     * @returns the snapshot, the import report and the freeze report
+     */
+    importGraph(input: ImportInput, options?: ImportGraphOptions): Promise<ImportGraphResult>;
+    /**
+     * Write a snapshot in a format, as UTF-8 chunks (design section 8.5).
+     * @param snapshot - the snapshot
+     * @param format - the format name
+     * @param options - the exporter's common and format-specific options
+     * @returns the encoded chunks
+     */
+    exportGraph(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): AsyncIterable<Uint8Array>;
+    /**
+     * Write a snapshot in a format, as one string.
+     * @param snapshot - the snapshot
+     * @param format - the format name
+     * @param options - the exporter's common and format-specific options
+     * @returns the whole document
+     */
+    exportGraphToString(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): Promise<string>;
+    /**
+     * What exporting a snapshot in a format would lose, without writing anything.
+     * @param snapshot - the snapshot
+     * @param format - the format name
+     * @param options - the exporter's common and format-specific options
+     * @returns the loss notes, empty when the export is exact
+     */
+    checkExport(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): readonly LossNote[];
+}
+/**
+ * A registry holding the eight built-in importers and exporters in the order of GRAPH_FORMATS.
+ * @returns a new registry
+ */
+export declare function createRegistry(): FormatRegistry;
+/** The default registry: every built-in format. */
+export declare const registry: FormatRegistry;
+/**
+ * Read an input into a fresh builder and freeze it, through the default registry (design section
+ * 8.4: `importGraph(input, { format?, ...options })`).
+ * @param input - the text, bytes, stream or chunks to read
+ * @param options - the format, hints, common and format-specific import options
+ * @returns the snapshot, the import report and the freeze report
+ */
+export declare function importGraph(input: ImportInput, options?: ImportGraphOptions): Promise<ImportGraphResult>;
+/**
+ * Write a snapshot in a format through the default registry, as UTF-8 chunks.
+ * @param snapshot - the snapshot
+ * @param format - the format name
+ * @param options - the exporter's common and format-specific options
+ * @returns the encoded chunks
+ */
+export declare function exportGraph(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): AsyncIterable<Uint8Array>;
+/**
+ * Write a snapshot in a format through the default registry, as one string.
+ * @param snapshot - the snapshot
+ * @param format - the format name
+ * @param options - the exporter's common and format-specific options
+ * @returns the whole document
+ */
+export declare function exportGraphToString(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): Promise<string>;
+/**
+ * What exporting a snapshot in a format would lose, through the default registry.
+ * @param snapshot - the snapshot
+ * @param format - the format name
+ * @param options - the exporter's common and format-specific options
+ * @returns the loss notes, empty when the export is exact
+ */
+export declare function checkExport(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): readonly LossNote[];
+/**
+ * Sniff an input's format through the default registry.
+ * @param hints - the filename, MIME type and / or head of the input
+ * @returns the best candidate, or null when no built-in importer claims it
+ */
+export declare function sniff(hints: SniffHints): SniffResult | null;
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACH,KAAK,aAAa,EAClB,KAAK,YAAY,EAEjB,KAAK,mBAAmB,EAExB,KAAK,aAAa,EACrB,MAAM,uBAAuB,CAAC;AAY/B,OAAO,EAAiC,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9F,OAAO,EACH,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,QAAQ,EAChB,MAAM,YAAY,CAAC;AAEpB,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AAEtD,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG,IAAI,CAC1B,mBAAmB,EACnB,UAAU,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,WAAW,GAAG,aAAa,CAClF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC3D,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,mEAAmE;IACnE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CACjC;AAED,+GAA+G;AAC/G,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC3D,mEAAmE;IACnE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C;AAKD;;;;GAIG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAEhE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAEhE;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAK/C;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAK/C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAQvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAQvC;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIpC;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIpC;;;OAGG;IACH,SAAS,IAAI,SAAS,aAAa,EAAE;IAIrC;;;OAGG;IACH,SAAS,IAAI,SAAS,aAAa,EAAE;IAIrC;;;OAGG;IACH,OAAO,IAAI,SAAS,MAAM,EAAE;IAI5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,WAAW,EAAE;IAInD;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAK5C;;;;;;;;OAQG;IACG,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAgDnG;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAAC,UAAU,CAAC;IAI7G;;;;;;OAMG;IACG,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjH;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,QAAQ,EAAE;CAG1G;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAkB/C;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,EAAE,cAAiC,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAExG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACvB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC7B,aAAa,CAAC,UAAU,CAAC,CAE3B;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACrC,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACvB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC7B,SAAS,QAAQ,EAAE,CAErB;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAE3D"}