@graphty/graph-io 0.3.25 → 0.3.27

package/dist/src/common/report.d.ts

@@ -10,10 +10,16 @@
  * (an ImportError, an abort reason, a programming error) unchanged.
  */
 import { ImportError, type ImportIssue, type ImportReport, type IssueCategory, type LossNote } from "../types.js";
+/**
+ * The most warnings of one code a report keeps; later ones are counted in one W_ISSUES_SUPPRESSED
+ * warning, so a per-row warning on a large file cannot grow the report without bound.
+ * @category Issue and loss codes
+ */
+export declare const MAX_WARNINGS_PER_CODE = 1000;
 /**
  * Where an issue was found: the 1-based line and the element (id or attribute name) when known.
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Writing a format
  */
 export interface IssueLocation {
     /** The 1-based source line, when known. */
@@ -23,8 +29,8 @@ export interface IssueLocation {
 }
 /**
  * The mutable element counters of a report in progress; importers increment them directly in hot loops.
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Plugin helpers
  */
 export interface MutableCounts {
     /** Nodes pushed. */
@@ -35,21 +41,19 @@ export interface MutableCounts {
     skippedNodes: number;
     /** Edges skipped after an error. */
     skippedEdges: number;
-    /** Source edges expanded into two logical edges (design section 3.6). */
+    /** Source edges expanded into two logical edges. */
     expandedMixed: number;
 }
 /**
- * The code a report used to give a thrown value that was not a GraphFormatError. Since audit round
- * 1 such a value (a TypeError, a RangeError: a bug in an importer or a sink, never a defect of the
- * input) propagates out of import() untouched, so no importer records this code any more; the
- * constant stays for consumers that switch on the codes of earlier reports.
+ * No longer recorded; kept so code that switches on older reports still compiles.
+ * @category Issue and loss codes
  */
 export declare const PARSE_ERROR_CODE = "E_PARSE";
 /**
  * Accumulates an ImportReport while an importer runs. Errors count toward the error limit; the
  * error that takes the count beyond the limit is still recorded, `truncated` is set, and an
- * ImportError carrying the report so far is thrown (design section 8.4: "beyond it the importer
- * aborts with E_IMPORT"). Warnings never abort.
+ * ImportError carrying the report so far is thrown. Warnings never abort.
+ * @category Writing a format
  */
 export declare class ImportReportBuilder {
     /** The importer's format name. */
@@ -61,6 +65,8 @@ export declare class ImportReportBuilder {
     private readonly issueList;
     private readonly lossList;
     private readonly onceCodes;
+    /** Warnings recorded per code, kept or not. */
+    private readonly warningsByCode;
     private errors;
     private warnings;
     private truncatedFlag;
@@ -107,7 +113,9 @@ export declare class ImportReportBuilder {
      */
     error(category: IssueCategory, code: string, message: string, where?: IssueLocation): ImportIssue;
     /**
-     * Record a warning; warnings never count toward the limit.
+     * Record a warning; warnings never count toward the limit. Beyond MAX_WARNINGS_PER_CODE
+     * warnings of one code the warning is counted, not kept: finish() adds one W_ISSUES_SUPPRESSED
+     * warning per such code with the number dropped.
      * @param category - the issue category
      * @param code - a stable code such as "W_WIDENED"
      * @param message - a plain-ASCII message
@@ -137,7 +145,7 @@ export declare class ImportReportBuilder {
      */
     loss(code: string, message: string, column?: string | null, count?: number | null): LossNote;
     /**
-     * The per-element catch of design section 8.6: record a thrown GraphFormatError as an error
+     * The per-element catch: record a thrown GraphFormatError as an error
      * issue with its code and the category the code implies. Anything else is re-thrown unchanged:
      * an ImportError (the import already aborted), an abort reason, and any other thrown value (a
      * TypeError or RangeError is a programming error in the importer or the sink, never a defect of
@@ -147,6 +155,13 @@ export declare class ImportReportBuilder {
      * @returns the recorded issue
      */
     recordError(err: unknown, where?: IssueLocation): ImportIssue;
+    /**
+     * A builder that starts from everything this one recorded so far: issues, counts, loss notes,
+     * the warnOnce keys, the error and warning counts and the truncation flag. For an importer that
+     * reads its input once and emits several graphs, each with its own report.
+     * @returns the copy; later records to either builder do not reach the other
+     */
+    fork(): ImportReportBuilder;
     /**
      * Build the ImportError that aborts the import, carrying the report so far. The caller throws
      * it; this method only constructs it so it can be used in expression position.
@@ -164,6 +179,34 @@ export declare class ImportReportBuilder {
      * @param details - optional machine-readable context for the ImportError
      */
     fail(code: string, message: string, where?: IssueLocation, details?: Readonly<Record<string, unknown>>): never;
+    /**
+     * Record a fatal error of any category and abort, as fail() does for a parse error: a size
+     * limit (E_TOO_LARGE, category "unsupported") stops an import without being a defect of the
+     * syntax. A fatal error is not the error limit: `truncated` stays as it was.
+     * @param category - the issue category
+     * @param code - a stable code
+     * @param message - a plain-ASCII message
+     * @param where - the line and element, when known
+     * @param details - optional machine-readable context for the ImportError
+     */
+    failWith(category: IssueCategory, code: string, message: string, where?: IssueLocation, details?: Readonly<Record<string, unknown>>): never;
+    /**
+     * Add a finished report to this one: its issues after the ones recorded so far, its counts, its
+     * loss notes and its truncated flag. Use it when an importer hands part of the work to another
+     * importer (for example, a wrapper around the CSV importer) and returns one report for both. The issues
+     * keep their codes; errors added this way do not count toward this report's error limit, since
+     * the other importer applied its own.
+     * @param report - the report the other importer returned
+     * @returns this builder
+     * @example
+     * ```ts
+     * const report = new ImportReportBuilder("netscope", opts.errorLimit);
+     * const text = await readText(input, report, opts);
+     * report.include(await csvImporter.import(text, sink, options));
+     * return report.finish();
+     * ```
+     */
+    include(report: ImportReport): this;
     /**
      * The report as it stands: a frozen snapshot with the parse duration so far. Can be called more
      * than once; each call reflects everything recorded up to that point.
@@ -172,16 +215,31 @@ export declare class ImportReportBuilder {
     finish(): ImportReport;
 }
 /**
- * Whether a thrown value is an abort reason (the DOMException or Error named "AbortError" that
- * AbortSignal.reason holds), which an importer must let through untouched.
+ * Whether a thrown value means the load was cancelled rather than failed: the DOMException or Error
+ * named "AbortError" that an aborted signal throws, or the "TimeoutError" of AbortSignal.timeout().
+ * Use it in a `catch` block to say nothing to the user when they cancelled. A custom reason passed
+ * to `abort(reason)` is not recognized: compare it with `signal.reason`. A format plugin uses it to
+ * let a cancellation through untouched.
  * @param err - the thrown value
- * @returns true for an AbortError
+ * @returns true for an AbortError or a TimeoutError
+ * @example
+ * ```ts
+ * try {
+ *     await loadFromUrl(url, { signal });
+ * } catch (err) {
+ *     if (!isAbortError(err)) {
+ *         showError(err);
+ *     }
+ * }
+ * ```
+ * @category Reports and errors
  */
 export declare function isAbortError(err: unknown): boolean;
 /**
  * The message of a thrown value: an Error's message, a string as is, anything else described by type.
  * @param err - the thrown value
  * @returns a plain message
+ * @category Plugin helpers
  */
 export declare function messageOf(err: unknown): string;
 //# sourceMappingURL=report.d.ts.map

package/dist/src/common/report.d.ts.map

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

package/dist/src/common/report.js

@@ -11,6 +11,14 @@
  */
 import { GraphFormatError } from "@graphty/graph-format";
 import { ImportError } from "../types.js";
+import { ISSUES_SUPPRESSED_CODE } from "./codes.js";
+import { agree, plural } from "./plural.js";
+/**
+ * The most warnings of one code a report keeps; later ones are counted in one W_ISSUES_SUPPRESSED
+ * warning, so a per-row warning on a large file cannot grow the report without bound.
+ * @category Issue and loss codes
+ */
+export const MAX_WARNINGS_PER_CODE = 1000;
 /**
  * The category a thrown GraphFormatError maps to when an importer catches it per element: the codes
  * that mean "the file referenced something it never declared" are missing values, a refused
@@ -26,17 +34,28 @@ const CATEGORY_BY_CODE = {
     E_GPU_INELIGIBLE: "unsupported",
 };
 /**
- * The code a report used to give a thrown value that was not a GraphFormatError. Since audit round
- * 1 such a value (a TypeError, a RangeError: a bug in an importer or a sink, never a defect of the
- * input) propagates out of import() untouched, so no importer records this code any more; the
- * constant stays for consumers that switch on the codes of earlier reports.
+ * No longer recorded; kept so code that switches on older reports still compiles.
+ * @category Issue and loss codes
  */
 export const PARSE_ERROR_CODE = "E_PARSE";
+/**
+ * An issue message as the ImportError shows it: prefixed with its line when the issue has one and the
+ * message does not already name it.
+ * @param message - the issue message
+ * @param where - the issue location
+ * @returns the message for the error
+ */
+function withLine(message, where) {
+    const line = where?.line;
+    return line === undefined || line === null || message.includes(`line ${line}`)
+        ? message
+        : `line ${line}: ${message}`;
+}
 /**
  * Accumulates an ImportReport while an importer runs. Errors count toward the error limit; the
  * error that takes the count beyond the limit is still recorded, `truncated` is set, and an
- * ImportError carrying the report so far is thrown (design section 8.4: "beyond it the importer
- * aborts with E_IMPORT"). Warnings never abort.
+ * ImportError carrying the report so far is thrown. Warnings never abort.
+ * @category Writing a format
  */
 export class ImportReportBuilder {
     /**
@@ -50,6 +69,8 @@ export class ImportReportBuilder {
         this.issueList = [];
         this.lossList = [];
         this.onceCodes = new Set();
+        /** Warnings recorded per code, kept or not. */
+        this.warningsByCode = new Map();
         this.errors = 0;
         this.warnings = 0;
         this.truncatedFlag = false;
@@ -107,7 +128,7 @@ export class ImportReportBuilder {
         this.errors++;
         if (this.errors > this.errorLimit) {
             this.truncatedFlag = true;
-            throw this.abort(`error limit of ${this.errorLimit} exceeded: ${message}`, {
+            throw this.abort(`error limit of ${this.errorLimit} exceeded: ${withLine(message, where)}`, {
                 code,
                 limit: this.errorLimit,
             });
@@ -115,7 +136,9 @@ export class ImportReportBuilder {
         return issue;
     }
     /**
-     * Record a warning; warnings never count toward the limit.
+     * Record a warning; warnings never count toward the limit. Beyond MAX_WARNINGS_PER_CODE
+     * warnings of one code the warning is counted, not kept: finish() adds one W_ISSUES_SUPPRESSED
+     * warning per such code with the number dropped.
      * @param category - the issue category
      * @param code - a stable code such as "W_WIDENED"
      * @param message - a plain-ASCII message
@@ -124,8 +147,12 @@ export class ImportReportBuilder {
      */
     warning(category, code, message, where) {
         const issue = makeIssue(category, "warning", code, message, where);
-        this.issueList.push(issue);
-        this.warnings++;
+        const seen = (this.warningsByCode.get(code) ?? 0) + 1;
+        this.warningsByCode.set(code, seen);
+        if (seen <= MAX_WARNINGS_PER_CODE) {
+            this.issueList.push(issue);
+            this.warnings++;
+        }
         return issue;
     }
     /**
@@ -160,7 +187,7 @@ export class ImportReportBuilder {
         return note;
     }
     /**
-     * The per-element catch of design section 8.6: record a thrown GraphFormatError as an error
+     * The per-element catch: record a thrown GraphFormatError as an error
      * issue with its code and the category the code implies. Anything else is re-thrown unchanged:
      * an ImportError (the import already aborted), an abort reason, and any other thrown value (a
      * TypeError or RangeError is a programming error in the importer or the sink, never a defect of
@@ -172,10 +199,36 @@ export class ImportReportBuilder {
     recordError(err, where) {
         if (err instanceof GraphFormatError && !(err instanceof ImportError)) {
             const category = CATEGORY_BY_CODE[err.code] ?? "validation-error";
+            if (err.code === "E_TOO_LARGE") {
+                // the sink is full: every later element would fail the same way, so the import stops
+                return this.failWith(category, err.code, err.message, where);
+            }
             return this.error(category, err.code, err.message, where);
         }
         throw err;
     }
+    /**
+     * A builder that starts from everything this one recorded so far: issues, counts, loss notes,
+     * the warnOnce keys, the error and warning counts and the truncation flag. For an importer that
+     * reads its input once and emits several graphs, each with its own report.
+     * @returns the copy; later records to either builder do not reach the other
+     */
+    fork() {
+        const copy = new ImportReportBuilder(this.format, this.errorLimit);
+        Object.assign(copy.counts, this.counts);
+        copy.issueList.push(...this.issueList);
+        copy.lossList.push(...this.lossList);
+        for (const key of this.onceCodes) {
+            copy.onceCodes.add(key);
+        }
+        for (const [code, count] of this.warningsByCode) {
+            copy.warningsByCode.set(code, count);
+        }
+        copy.errors = this.errors;
+        copy.warnings = this.warnings;
+        copy.truncatedFlag = this.truncatedFlag;
+        return copy;
+    }
     /**
      * Build the ImportError that aborts the import, carrying the report so far. The caller throws
      * it; this method only constructs it so it can be used in expression position.
@@ -195,13 +248,58 @@ export class ImportReportBuilder {
      * @param details - optional machine-readable context for the ImportError
      */
     fail(code, message, where, details) {
-        const issue = makeIssue("parse-error", "error", code, message, where);
-        this.issueList.push(issue);
+        this.failWith("parse-error", code, message, where, details);
+    }
+    /**
+     * Record a fatal error of any category and abort, as fail() does for a parse error: a size
+     * limit (E_TOO_LARGE, category "unsupported") stops an import without being a defect of the
+     * syntax. A fatal error is not the error limit: `truncated` stays as it was.
+     * @param category - the issue category
+     * @param code - a stable code
+     * @param message - a plain-ASCII message
+     * @param where - the line and element, when known
+     * @param details - optional machine-readable context for the ImportError
+     */
+    failWith(category, code, message, where, details) {
+        this.issueList.push(makeIssue(category, "error", code, message, where));
         this.errors++;
-        if (this.errors > this.errorLimit) {
-            this.truncatedFlag = true;
+        throw this.abort(withLine(message, where), { code, ...details });
+    }
+    /**
+     * Add a finished report to this one: its issues after the ones recorded so far, its counts, its
+     * loss notes and its truncated flag. Use it when an importer hands part of the work to another
+     * importer (for example, a wrapper around the CSV importer) and returns one report for both. The issues
+     * keep their codes; errors added this way do not count toward this report's error limit, since
+     * the other importer applied its own.
+     * @param report - the report the other importer returned
+     * @returns this builder
+     * @example
+     * ```ts
+     * const report = new ImportReportBuilder("netscope", opts.errorLimit);
+     * const text = await readText(input, report, opts);
+     * report.include(await csvImporter.import(text, sink, options));
+     * return report.finish();
+     * ```
+     */
+    include(report) {
+        for (const issue of report.issues) {
+            this.issueList.push(issue);
+            if (issue.severity === "error") {
+                this.errors++;
+            }
+            else {
+                this.warnings++;
+            }
         }
-        throw this.abort(message, { code, ...details });
+        const { counts } = report;
+        this.counts.nodes += counts.nodes;
+        this.counts.edges += counts.edges;
+        this.counts.skippedNodes += counts.skippedNodes;
+        this.counts.skippedEdges += counts.skippedEdges;
+        this.counts.expandedMixed += counts.expandedMixed;
+        this.lossList.push(...report.lossy);
+        this.truncatedFlag || (this.truncatedFlag = report.truncated);
+        return this;
     }
     /**
      * The report as it stands: a frozen snapshot with the parse duration so far. Can be called more
@@ -210,12 +308,19 @@ export class ImportReportBuilder {
      */
     finish() {
         const { nodes, edges, skippedNodes, skippedEdges, expandedMixed } = this.counts;
+        const suppressed = [];
+        for (const [code, seen] of this.warningsByCode) {
+            if (seen > MAX_WARNINGS_PER_CODE) {
+                const more = seen - MAX_WARNINGS_PER_CODE;
+                suppressed.push(makeIssue("unsupported", "warning", ISSUES_SUPPRESSED_CODE, `${more} more ${code} warning${plural(more)} ${agree(more, "was", "were")} not kept (the report keeps the first ${MAX_WARNINGS_PER_CODE})`, { element: code }));
+            }
+        }
         return Object.freeze({
             format: this.format,
             counts: Object.freeze({ nodes, edges, skippedNodes, skippedEdges, expandedMixed }),
-            issues: Object.freeze([...this.issueList]),
+            issues: Object.freeze([...this.issueList, ...suppressed]),
             errorCount: this.errors,
-            warningCount: this.warnings,
+            warningCount: this.warnings + suppressed.length,
             truncated: this.truncatedFlag,
             lossy: Object.freeze([...this.lossList]),
             durationMs: now() - this.startedAt,
@@ -242,18 +347,37 @@ function makeIssue(category, severity, code, message, where) {
     });
 }
 /**
- * Whether a thrown value is an abort reason (the DOMException or Error named "AbortError" that
- * AbortSignal.reason holds), which an importer must let through untouched.
+ * Whether a thrown value means the load was cancelled rather than failed: the DOMException or Error
+ * named "AbortError" that an aborted signal throws, or the "TimeoutError" of AbortSignal.timeout().
+ * Use it in a `catch` block to say nothing to the user when they cancelled. A custom reason passed
+ * to `abort(reason)` is not recognized: compare it with `signal.reason`. A format plugin uses it to
+ * let a cancellation through untouched.
  * @param err - the thrown value
- * @returns true for an AbortError
+ * @returns true for an AbortError or a TimeoutError
+ * @example
+ * ```ts
+ * try {
+ *     await loadFromUrl(url, { signal });
+ * } catch (err) {
+ *     if (!isAbortError(err)) {
+ *         showError(err);
+ *     }
+ * }
+ * ```
+ * @category Reports and errors
  */
 export function isAbortError(err) {
-    return typeof err === "object" && err !== null && err.name === "AbortError";
+    if (typeof err !== "object" || err === null) {
+        return false;
+    }
+    const { name } = err;
+    return name === "AbortError" || name === "TimeoutError";
 }
 /**
  * The message of a thrown value: an Error's message, a string as is, anything else described by type.
  * @param err - the thrown value
  * @returns a plain message
+ * @category Plugin helpers
  */
 export function messageOf(err) {
     if (err instanceof Error) {

package/dist/src/common/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/common/report.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/common/report.ts"],"names":[],"mappings":"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"}

package/dist/src/common/temporal.d.ts

@@ -10,30 +10,43 @@
  * grammar rather than Date.parse, so two hosts agree on every value.
  */
 import { type ColumnDecl, type ColumnRole } from "@graphty/graph-format";
-/** The temporal kinds a declared type can map to; each fixes the parse grammar and the canonical text. */
+/**
+ * The temporal kinds a declared type can map to; each fixes the parse grammar and the canonical text.
+ * @category Plugin helpers
+ */
 export type TemporalKind = "date" | "dateTime" | "localDateTime" | "time" | "localTime";
 /**
  * The GEXF `timeformat` values (design section 5.9).
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Plugin helpers
  */
 export type TimeFormat = "integer" | "double" | "date" | "dateTime";
-/** A parsed temporal value: the number stored in the column and the source text when it must be kept. */
+/**
+ * A parsed temporal value: the number stored in the column and the source text when it must be kept.
+ * @category Plugin helpers
+ */
 export interface TemporalValue {
     /** Epoch milliseconds (date, dateTime, localDateTime), milliseconds since midnight (time, localTime), or the raw number. */
     readonly value: number;
     /** The source text when formatTemporal(value) would not reproduce it; null otherwise. */
     readonly text: string | null;
 }
-/** The role of a companion text column. */
+/**
+ * The role of a companion text column.
+ * @category Plugin helpers
+ */
 export declare const TIME_TEXT_ROLE: ColumnRole;
-/** The suffix of a companion text column's name. */
+/**
+ * The suffix of a companion text column's name.
+ * @category Plugin helpers
+ */
 export declare const TIME_TEXT_SUFFIX = ".text";
 /**
  * Parse an ISO-8601 temporal text of one kind.
  * @param text - the source text (already trimmed)
  * @param kind - the temporal kind
  * @returns the value and, when the canonical form differs, the source text; E_COLUMN_TYPE when the text is not of the kind
+ * @category Plugin helpers
  */
 export declare function parseTemporal(text: string, kind: TemporalKind): TemporalValue;
 /**
@@ -44,6 +57,7 @@ export declare function parseTemporal(text: string, kind: TemporalKind): Tempora
  * @param text - the source text
  * @param timeFormat - the graph's timeformat, or null when the file declares none
  * @returns the value and the source text when it must be kept
+ * @category Plugin helpers
  */
 export declare function parseTimeText(text: string, timeFormat: TimeFormat | null): TemporalValue;
 /**
@@ -52,6 +66,7 @@ export declare function parseTimeText(text: string, timeFormat: TimeFormat | nul
  * @param kind - the temporal kind
  * @returns the canonical text: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS[.mmm]Z`, `YYYY-MM-DDTHH:MM:SS[.mmm]`,
  * `HH:MM:SS[.mmm]Z` or `HH:MM:SS[.mmm]`
+ * @category Plugin helpers
  */
 export declare function formatTemporal(value: number, kind: TemporalKind): string;
 /**
@@ -60,12 +75,14 @@ export declare function formatTemporal(value: number, kind: TemporalKind): strin
  * @param value - the value as stored
  * @param timeFormat - the graph's timeformat, or null for a file that declares none (double)
  * @returns the text
+ * @category Plugin helpers
  */
 export declare function formatTimeValue(value: number, timeFormat: TimeFormat | null): string;
 /**
  * The declaration of the companion text column of a temporal column (design section 5.1).
  * @param column - the temporal column's name
  * @returns a string column named `<column>.text` with role timeText and `extra.for` naming the column
+ * @category Plugin helpers
  */
 export declare function timeTextCompanion(column: string): ColumnDecl;
 //# sourceMappingURL=temporal.d.ts.map

package/dist/src/common/temporal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../../src/common/temporal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,uBAAuB,CAAC;AAE3F,0GAA0G;AAC1G,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpE,yGAAyG;AACzG,MAAM,WAAW,aAAa;IAC1B,4HAA4H;IAC5H,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,2CAA2C;AAC3C,eAAO,MAAM,cAAc,EAAE,UAAuB,CAAC;AAErD,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAUxC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAmB7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,aAAa,CAiBxF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CA2BxE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAepF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAQ5D"}
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../../src/common/temporal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,uBAAuB,CAAC;AAE3F;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B,4HAA4H;IAC5H,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,UAAuB,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAUxC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAmB7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,aAAa,CAiBxF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CA2BxE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAepF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAQ5D"}

package/dist/src/common/temporal.js

@@ -10,9 +10,15 @@
  * grammar rather than Date.parse, so two hosts agree on every value.
  */
 import { GraphFormatError } from "@graphty/graph-format";
-/** The role of a companion text column. */
+/**
+ * The role of a companion text column.
+ * @category Plugin helpers
+ */
 export const TIME_TEXT_ROLE = "timeText";
-/** The suffix of a companion text column's name. */
+/**
+ * The suffix of a companion text column's name.
+ * @category Plugin helpers
+ */
 export const TIME_TEXT_SUFFIX = ".text";
 const DATE_TIME = /^(-?[0-9]{4,})-([0-9]{2})-([0-9]{2})(?:[T ]([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]{1,9}))?)?)?(Z|z|[+-][0-9]{2}(?::?[0-9]{2})?)?$/;
 const TIME = /^([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]{1,9}))?)?(Z|z|[+-][0-9]{2}(?::?[0-9]{2})?)?$/;
@@ -24,6 +30,7 @@ const MS_PER_DAY = 86400000;
  * @param text - the source text (already trimmed)
  * @param kind - the temporal kind
  * @returns the value and, when the canonical form differs, the source text; E_COLUMN_TYPE when the text is not of the kind
+ * @category Plugin helpers
  */
 export function parseTemporal(text, kind) {
     let value;
@@ -53,6 +60,7 @@ export function parseTemporal(text, kind) {
  * @param text - the source text
  * @param timeFormat - the graph's timeformat, or null when the file declares none
  * @returns the value and the source text when it must be kept
+ * @category Plugin helpers
  */
 export function parseTimeText(text, timeFormat) {
     const trimmed = text.trim();
@@ -78,6 +86,7 @@ export function parseTimeText(text, timeFormat) {
  * @param kind - the temporal kind
  * @returns the canonical text: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS[.mmm]Z`, `YYYY-MM-DDTHH:MM:SS[.mmm]`,
  * `HH:MM:SS[.mmm]Z` or `HH:MM:SS[.mmm]`
+ * @category Plugin helpers
  */
 export function formatTemporal(value, kind) {
     switch (kind) {
@@ -113,6 +122,7 @@ export function formatTemporal(value, kind) {
  * @param value - the value as stored
  * @param timeFormat - the graph's timeformat, or null for a file that declares none (double)
  * @returns the text
+ * @category Plugin helpers
  */
 export function formatTimeValue(value, timeFormat) {
     switch (timeFormat) {
@@ -134,6 +144,7 @@ export function formatTimeValue(value, timeFormat) {
  * The declaration of the companion text column of a temporal column (design section 5.1).
  * @param column - the temporal column's name
  * @returns a string column named `<column>.text` with role timeText and `extra.for` naming the column
+ * @category Plugin helpers
  */
 export function timeTextCompanion(column) {
     return {