@graphty/graph-io 0.3.46 → 0.3.48

package/dist/src/sources/cypher/types-map.js

@@ -0,0 +1,306 @@
+/**
+ * The one type mapper of the Cypher source (design section 10): every transport's wire values --
+ * Neo4j's typed JSON, neo4j-driver's objects, Neptune's plain JSON -- become the same plain values,
+ * and every node, relationship and path becomes a GraphNode, a GraphRel or an array of them.
+ *
+ * - Integers: a number while it is exact; past 2^53 the `long` parameter picks a rounded number
+ *   (W_PRECISION, once per column) or the exact digits as a string.
+ * - Floats, booleans, strings: as they are. Dates and instants: epoch milliseconds. Local times,
+ *   times and durations: their ISO text. Points: `{ srid, x, y, z? }`. Lists and maps: arrays and
+ *   objects of mapped values. Bytes: dropped (W_SOURCE_VALUE).
+ */
+import { PRECISION_CODE } from "../../common/codes.js";
+import { warnOn } from "../fail.js";
+/** A node a query returned. */
+export class GraphNode {
+    /**
+     * Create one.
+     * @param id - the server's element id
+     * @param labels - its labels
+     * @param properties - its mapped properties
+     */
+    constructor(id, labels, properties) {
+        this.id = id;
+        this.labels = labels;
+        this.properties = properties;
+    }
+}
+/** A relationship a query returned. */
+export class GraphRel {
+    /**
+     * Create one.
+     * @param id - the server's element id
+     * @param start - the start node's element id
+     * @param end - the end node's element id
+     * @param type - its type
+     * @param properties - its mapped properties
+     */
+    constructor(id, start, end, type, properties) {
+        this.id = id;
+        this.start = start;
+        this.end = end;
+        this.type = type;
+        this.properties = properties;
+    }
+}
+/** Values past this need a 64-bit integer. */
+const SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * An integer from its exact decimal digits.
+ * @param digits - the digits
+ * @param column - the column it belongs to, for the warning
+ * @param m - the map context
+ * @returns a number, or a string past 2^53 under `long: "string"`
+ */
+function integer(digits, column, m) {
+    let big;
+    try {
+        big = BigInt(digits);
+    }
+    catch {
+        return Number(digits);
+    }
+    if (big <= SAFE && big >= -SAFE) {
+        return Number(big);
+    }
+    if (m.long === "string") {
+        return big.toString();
+    }
+    m.report.warnOnce("precision", PRECISION_CODE, `column ${column}: an integer beyond 2^53 was stored as the nearest 64-bit float; pass long: "string" to keep every digit`, undefined, `${PRECISION_CODE}:${column}`);
+    return Number(big);
+}
+/**
+ * Epoch milliseconds of an ISO instant, the zone name in brackets ignored; the text itself when it
+ * does not parse.
+ * @param text - the ISO text
+ * @param type - the server's type name
+ * @param column - the column
+ * @param m - the map context
+ * @returns milliseconds, or the text
+ */
+function epoch(text, type, column, m) {
+    const ms = Date.parse(withoutZoneName(text));
+    if (Number.isNaN(ms)) {
+        warnOn(m.report, "W_SOURCE_VALUE", `column ${column}: a ${type} kept as text`, { type, column, as: "string" });
+        return text;
+    }
+    return ms;
+}
+/**
+ * Warn that a value with no dtype was dropped; the caller leaves the property out.
+ * @param type - the server's type name
+ * @param column - the column
+ * @param m - the map context
+ */
+function dropped(type, column, m) {
+    warnOn(m.report, "W_SOURCE_VALUE", `column ${column}: a ${type} value was dropped`, {
+        type,
+        column,
+        as: "dropped",
+    });
+}
+/**
+ * Map every property of a map, leaving out dropped values.
+ * @param value - the map
+ * @param each - maps one value, given its key
+ * @returns the mapped map
+ */
+function mapEntries(value, each) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        const mapped = each(v, k);
+        if (mapped !== undefined) {
+            out[k] = mapped;
+        }
+    }
+    return out;
+}
+/**
+ * A WKT point as Neo4j's typed JSON spells it ("SRID=7203;POINT (1.0 2.0)").
+ * @param text - the text
+ * @returns `{ srid, x, y, z? }`, or the text when it does not parse
+ */
+function wktPoint(text) {
+    const match = /^SRID=(\d+);POINT(?: Z)? ?\(([^)]*)\)$/i.exec(text.trim());
+    if (match === null) {
+        return text;
+    }
+    const [x = 0, y = 0, z] = match[2].trim().split(/\s+/).map(Number);
+    return z === undefined ? { srid: Number(match[1]), x, y } : { srid: Number(match[1]), x, y, z };
+}
+/**
+ * Map a value of Neo4j's typed JSON (the Query API's `application/vnd.neo4j.query.v1.1`).
+ * @param v - the wire value
+ * @param column - the result column or property key it belongs to
+ * @param m - the map context
+ * @returns the plain value, a GraphNode, a GraphRel or an array; undefined when dropped
+ */
+export function fromTypedJson(v, column, m) {
+    if (v === null || typeof v !== "object" || !("$type" in v)) {
+        return v ?? null;
+    }
+    const { $type: type, _value: value } = v;
+    switch (type) {
+        case "Null":
+            return null;
+        case "Boolean":
+        case "String":
+            return value;
+        case "Integer":
+            return integer(String(value), column, m);
+        case "Float":
+            return Number(value);
+        case "Date":
+            return epoch(`${String(value)}T00:00:00Z`, type, column, m);
+        case "OffsetDateTime":
+        case "ZonedDateTime":
+            return epoch(String(value), type, column, m);
+        case "LocalDateTime":
+        case "LocalTime":
+        case "Time":
+        case "Duration":
+            return String(value);
+        case "Point":
+            return wktPoint(String(value));
+        case "Base64":
+            dropped(type, column, m);
+            return undefined;
+        case "List":
+            return value.map((x) => fromTypedJson(x, column, m));
+        case "Map":
+            return mapEntries(value, (x) => fromTypedJson(x, column, m));
+        case "Node": {
+            const n = value;
+            return new GraphNode(n._element_id, n._labels, mapEntries(n._properties, (x, k) => fromTypedJson(x, k, m)));
+        }
+        case "Relationship": {
+            const r = value;
+            return new GraphRel(r._element_id, r._start_node_element_id, r._end_node_element_id, r._type, mapEntries(r._properties, (x, k) => fromTypedJson(x, k, m)));
+        }
+        case "Path":
+            return value.map((x) => fromTypedJson(x, column, m));
+        default:
+            warnOn(m.report, "W_SOURCE_VALUE", `column ${column}: a ${type} kept as text`, {
+                type,
+                column,
+                as: "string",
+            });
+            return typeof value === "string" ? value : JSON.stringify(value);
+    }
+}
+/**
+ * The text without a trailing bracketed zone name (`...+01:00[Europe/Paris]`).
+ * @param text - the ISO text
+ * @returns the text without the zone name
+ */
+function withoutZoneName(text) {
+    const end = text.length - 1;
+    if (text[end] !== "]") {
+        return text;
+    }
+    const open = text.indexOf("[", text.lastIndexOf("]", end - 1) + 1);
+    return open === -1 || open >= end ? text : text.slice(0, open);
+}
+/**
+ * Map a driver node or relationship.
+ * @param e - the driver entity
+ * @param node - whether it is a node
+ * @param m - the map context
+ * @param t - the driver's type checks
+ * @returns a GraphNode or a GraphRel
+ */
+function fromEntity(e, node, m, t) {
+    const props = mapEntries(e.properties, (x, k) => fromDriver(x, k, m, t));
+    const id = e.elementId ?? String(e.identity);
+    return node
+        ? new GraphNode(id, [...(e.labels ?? [])], props)
+        : new GraphRel(id, e.startNodeElementId ?? String(e.start), e.endNodeElementId ?? String(e.end), e.type ?? "", props);
+}
+/**
+ * Map a driver point.
+ * @param p - the point
+ * @returns srid, x, y and z when it has one
+ */
+function fromPoint(p) {
+    const srid = Number(String(p.srid));
+    return p.z === undefined ? { srid, x: p.x, y: p.y } : { srid, x: p.x, y: p.y, z: p.z };
+}
+/**
+ * Map a value neo4j-driver returned. Its lossless Integer keeps every digit, so `long` decides.
+ * @param v - the driver value
+ * @param column - the result column or property key
+ * @param m - the map context
+ * @param t - the driver's type checks
+ * @returns the plain value, a GraphNode, a GraphRel or an array; undefined when dropped
+ */
+export function fromDriver(v, column, m, t) {
+    if (v === null || v === undefined) {
+        return null;
+    }
+    if (typeof v !== "object") {
+        return typeof v === "bigint" ? integer(v.toString(), column, m) : v;
+    }
+    // driver values (Integer, the temporal types) spell themselves exactly through toString()
+    const text = () => v.toString();
+    if (t.isInt(v)) {
+        return integer(text(), column, m);
+    }
+    if (t.isNode(v) || t.isRelationship(v)) {
+        return fromEntity(v, t.isNode(v), m, t);
+    }
+    if (t.isPath(v)) {
+        const p = v;
+        return [p.start, ...p.segments.flatMap((s) => [s.relationship, s.end])].map((x) => fromDriver(x, column, m, t));
+    }
+    if (t.isDate(v)) {
+        return epoch(`${text()}T00:00:00Z`, "Date", column, m);
+    }
+    if (t.isDateTime(v)) {
+        return epoch(text(), "DateTime", column, m);
+    }
+    if (t.isLocalDateTime(v) || t.isLocalTime(v) || t.isTime(v) || t.isDuration(v)) {
+        return text();
+    }
+    if (t.isPoint(v)) {
+        return fromPoint(v);
+    }
+    if (v instanceof Uint8Array || v instanceof ArrayBuffer) {
+        dropped("ByteArray", column, m);
+        return undefined;
+    }
+    if (Array.isArray(v)) {
+        return v.map((x) => fromDriver(x, column, m, t));
+    }
+    return mapEntries(v, (x) => fromDriver(x, column, m, t));
+}
+/**
+ * Map a value of Neptune's openCypher JSON: nodes `{ "~id", "~entityType": "node", "~labels",
+ * "~properties" }`, relationships adding `~start`, `~end`, `~type`. Its numbers are plain JSON, so
+ * an integer past 2^53 was already rounded on the wire (W_PRECISION).
+ * @param v - the wire value
+ * @param column - the result column or property key
+ * @param m - the map context
+ * @returns the plain value, a GraphNode, a GraphRel or an array
+ */
+export function fromNeptune(v, column, m) {
+    if (typeof v === "number" && Number.isInteger(v) && !Number.isSafeInteger(v)) {
+        return integer(BigInt(v).toString(), column, m);
+    }
+    if (v === null || typeof v !== "object") {
+        return v ?? null;
+    }
+    if (Array.isArray(v)) {
+        return v.map((x) => fromNeptune(x, column, m));
+    }
+    const o = v;
+    const props = () => mapEntries((o["~properties"] ?? {}), (x, k) => fromNeptune(x, k, m));
+    switch (o["~entityType"]) {
+        case "node":
+            return new GraphNode(String(o["~id"]), (o["~labels"] ?? []), props());
+        case "relationship":
+            return new GraphRel(String(o["~id"]), String(o["~start"]), String(o["~end"]), String(o["~type"]), props());
+        default:
+            return mapEntries(o, (x) => fromNeptune(x, column, m));
+    }
+}
+//# sourceMappingURL=types-map.js.map

package/dist/src/sources/cypher/types-map.js.map

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

package/dist/src/sources/define.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `defineSource` and the registration checks (design section 2): the id form, exactly one read
+ * method, and the declared features against the methods present. Also the parameter checks every
+ * load runs against the descriptor before any request.
+ */
+import { type ImportReportBuilder } from "../common/report.js";
+import { type GraphSource, type LazySource, type SourceDescriptor } from "./types.js";
+/**
+ * Check a loaded source: its id, exactly one read method, and its declared features.
+ * @param source - the source
+ * @param declared - features a lazy registration declared, if any
+ */
+export declare function checkSource(source: GraphSource<never>, declared?: SourceDescriptor): void;
+/**
+ * Check a lazy registration before its code is loaded.
+ * @param source - the lazy source
+ */
+export declare function checkLazySource(source: LazySource): void;
+/**
+ * Define a network source: returns it unchanged, with its parameter type inferred, after the
+ * registration checks (an id of lowercase letters, digits and dashes; exactly one of `records`,
+ * `file` and `import`; declared features backed by methods). A malformed source throws an
+ * ImportError whose `issue.code` is E_SOURCE_INVALID. Experimental.
+ * @param source - the source
+ * @returns the same source
+ * @example
+ * ```ts
+ * const people = defineSource({
+ *     id: "people",
+ *     async records(params: { team: string }, ctx) {
+ *         const rows = await ctx.fetchJson<{ id: string; name: string }[]>(`/api/people?team=${params.team}`);
+ *         return { nodes: rows };
+ *     },
+ * });
+ * ```
+ * @category Network sources
+ */
+export declare function defineSource<P>(source: GraphSource<P>): GraphSource<P>;
+/**
+ * Check params against a descriptor before any request: required ones present, numbers and
+ * integers in range, booleans, enums, URLs (never with a user name or password in them).
+ * @param params - the caller's params
+ * @param descriptor - the source's descriptor
+ * @param report - the load's report
+ */
+export declare function checkParams(params: Readonly<Record<string, unknown>>, descriptor: SourceDescriptor | undefined, report: ImportReportBuilder): void;
+//# sourceMappingURL=define.d.ts.map

package/dist/src/sources/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/sources/define.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACH,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,EAGxB,MAAM,YAAY,CAAC;AA0CpB;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAezF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAKxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAGtE;AAuDD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACvB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,UAAU,EAAE,gBAAgB,GAAG,SAAS,EACxC,MAAM,EAAE,mBAAmB,GAC5B,IAAI,CAiBN"}

package/dist/src/sources/define.js

@@ -0,0 +1,173 @@
+/**
+ * `defineSource` and the registration checks (design section 2): the id form, exactly one read
+ * method, and the declared features against the methods present. Also the parameter checks every
+ * load runs against the descriptor before any request.
+ */
+import { failAlone, failOn } from "./fail.js";
+/** Lowercase letters, digits and single dashes between them. */
+const ID_FORM = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** The optional methods and the feature each one is. */
+const FEATURE_METHODS = [
+    ["expand", "expand"],
+    ["probe", "probe"],
+    ["list", "list"],
+    ["validate", "validate"],
+];
+/**
+ * Refuse a malformed source.
+ * @param id - the source id
+ * @param reason - why
+ * @param message - for logs
+ */
+function invalid(id, reason, message) {
+    failAlone("E_SOURCE_INVALID", message, { id, reason });
+}
+/**
+ * Check a source id.
+ * @param id - the id
+ */
+function checkSourceId(id) {
+    if (typeof id !== "string" || !ID_FORM.test(id)) {
+        invalid(String(id), "id", `source id ${JSON.stringify(id)} must be lowercase letters, digits and dashes`);
+    }
+}
+/**
+ * The features a loaded source has, from its methods.
+ * @param source - the source
+ * @returns the features
+ */
+function featuresOf(source) {
+    return FEATURE_METHODS.filter(([, method]) => typeof source[method] === "function").map(([f]) => f);
+}
+/**
+ * Check a loaded source: its id, exactly one read method, and its declared features.
+ * @param source - the source
+ * @param declared - features a lazy registration declared, if any
+ */
+export function checkSource(source, declared) {
+    checkSourceId(source.id);
+    const reads = ["records", "file", "import"].filter((m) => typeof source[m] === "function");
+    if (reads.length !== 1) {
+        invalid(source.id, "read-methods", `source ${source.id} must have exactly one of records, file and import`);
+    }
+    const features = (declared ?? source.descriptor)?.features;
+    if (features !== undefined) {
+        const has = new Set(featuresOf(source));
+        for (const f of features) {
+            if (f !== "page" && !has.has(f)) {
+                invalid(source.id, "features", `source ${source.id} declares ${f} but has no ${f} method`);
+            }
+        }
+    }
+}
+/**
+ * Check a lazy registration before its code is loaded.
+ * @param source - the lazy source
+ */
+export function checkLazySource(source) {
+    checkSourceId(source.id);
+    if (typeof source.load !== "function" || typeof source.descriptor !== "object") {
+        invalid(source.id, "lazy", `lazy source ${source.id} needs a descriptor and a load function`);
+    }
+}
+/**
+ * Define a network source: returns it unchanged, with its parameter type inferred, after the
+ * registration checks (an id of lowercase letters, digits and dashes; exactly one of `records`,
+ * `file` and `import`; declared features backed by methods). A malformed source throws an
+ * ImportError whose `issue.code` is E_SOURCE_INVALID. Experimental.
+ * @param source - the source
+ * @returns the same source
+ * @example
+ * ```ts
+ * const people = defineSource({
+ *     id: "people",
+ *     async records(params: { team: string }, ctx) {
+ *         const rows = await ctx.fetchJson<{ id: string; name: string }[]>(`/api/people?team=${params.team}`);
+ *         return { nodes: rows };
+ *     },
+ * });
+ * ```
+ * @category Network sources
+ */
+export function defineSource(source) {
+    checkSource(source);
+    return source;
+}
+/**
+ * Why a number or integer param is wrong, if it is.
+ * @param p - the param's descriptor
+ * @param value - the value given
+ * @returns the reason, or null when it is fine
+ */
+function numberProblem(p, value) {
+    if (typeof value !== "number" || Number.isNaN(value) || (p.type === "integer" && !Number.isInteger(value))) {
+        return "type";
+    }
+    if ((p.min !== undefined && value < p.min) || (p.max !== undefined && value > p.max)) {
+        return "range";
+    }
+    return null;
+}
+/**
+ * Why a URL param is wrong, if it is.
+ * @param value - the value given
+ * @returns the reason, or null when it is fine
+ */
+function urlProblem(value) {
+    let url;
+    try {
+        url = new URL(typeof value === "string" ? value : "");
+    }
+    catch {
+        return "type";
+    }
+    return url.username !== "" || url.password !== "" ? "credentials-in-url" : null;
+}
+/**
+ * Why a present param value is wrong for its descriptor, if it is.
+ * @param p - the param's descriptor
+ * @param value - the value given (not undefined or null)
+ * @returns the reason, or null when it is fine
+ */
+function paramProblem(p, value) {
+    switch (p.type) {
+        case "integer":
+        case "number":
+            return numberProblem(p, value);
+        case "boolean":
+            return typeof value === "boolean" ? null : "type";
+        case "enum":
+            return p.values !== undefined && !p.values.some((v) => v.value === value) ? "enum" : null;
+        case "url":
+            return urlProblem(value);
+        default:
+            return null;
+    }
+}
+/**
+ * Check params against a descriptor before any request: required ones present, numbers and
+ * integers in range, booleans, enums, URLs (never with a user name or password in them).
+ * @param params - the caller's params
+ * @param descriptor - the source's descriptor
+ * @param report - the load's report
+ */
+export function checkParams(params, descriptor, report) {
+    if (typeof params !== "object" || params === null) {
+        failOn(report, "E_SOURCE_PARAM", "params must be an object", { name: "params", reason: "type" });
+    }
+    for (const p of descriptor?.params ?? []) {
+        const value = params[p.name];
+        const missing = value === undefined || value === null;
+        let reason = null;
+        if (!missing) {
+            reason = paramProblem(p, value);
+        }
+        else if (p.required === true && p.default === undefined) {
+            reason = "required";
+        }
+        if (reason !== null) {
+            failOn(report, "E_SOURCE_PARAM", `parameter ${p.name}: ${reason}`, { name: p.name, reason });
+        }
+    }
+}
+//# sourceMappingURL=define.js.map

package/dist/src/sources/define.js.map

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

package/dist/src/sources/fail.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Raising a network source issue: one place that turns a code and its params into an ImportError
+ * whose `issue.params` and `details` both carry the params, so callers branch on
+ * `err.issue.code` and read `err.issue.params` as with every other graph-io failure.
+ */
+import { ImportReportBuilder } from "../common/report.js";
+import { type SourceIssueCode } from "./codes.js";
+/**
+ * Abort a load with a source error, carrying the load's report so far plus the error.
+ * @param report - the load's report
+ * @param code - the code
+ * @param message - a plain-ASCII message, for logs
+ * @param params - the issue's values
+ * @returns never; it throws the ImportError
+ */
+export declare function failOn(report: ImportReportBuilder, code: SourceIssueCode, message: string, params: Readonly<Record<string, unknown>>): never;
+/**
+ * Raise a source error outside a load (registration, a credential factory).
+ * @param code - the code
+ * @param message - a plain-ASCII message, for logs
+ * @param params - the issue's values
+ * @param format - the report's format name
+ */
+export declare function failAlone(code: SourceIssueCode, message: string, params: Readonly<Record<string, unknown>>, format?: string): never;
+/**
+ * Record a source warning on a report.
+ * @param report - the report
+ * @param code - the code
+ * @param message - a plain-ASCII message, for logs
+ * @param params - the issue's values
+ */
+export declare function warnOn(report: ImportReportBuilder, code: SourceIssueCode, message: string, params: Readonly<Record<string, unknown>>): void;
+//# sourceMappingURL=fail.d.ts.map

package/dist/src/sources/fail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail.d.ts","sourceRoot":"","sources":["../../../src/sources/fail.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAYlD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAClB,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC1C,KAAK,CAIP;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACrB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,MAAM,SAAW,GAClB,KAAK,CAEP;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAClB,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC1C,IAAI,CAEN"}

package/dist/src/sources/fail.js

@@ -0,0 +1,49 @@
+/**
+ * Raising a network source issue: one place that turns a code and its params into an ImportError
+ * whose `issue.params` and `details` both carry the params, so callers branch on
+ * `err.issue.code` and read `err.issue.params` as with every other graph-io failure.
+ */
+import { ImportReportBuilder } from "../common/report.js";
+/** The category each code is filed under. */
+const CATEGORY = {
+    E_SOURCE_PARAM: "validation-error",
+    E_SOURCE_INVALID: "validation-error",
+    E_SOURCE_RESPONSE: "parse-error",
+    E_SOURCE_NOT_A_GRAPH: "parse-error",
+    E_SOURCE_NOT_FOUND: "missing-value",
+    E_SOURCE_UNKNOWN: "missing-value",
+};
+/**
+ * Abort a load with a source error, carrying the load's report so far plus the error.
+ * @param report - the load's report
+ * @param code - the code
+ * @param message - a plain-ASCII message, for logs
+ * @param params - the issue's values
+ * @returns never; it throws the ImportError
+ */
+export function failOn(report, code, message, params) {
+    // a fork, so a failure the runner turns into a warning (a later page's 401, a cap) leaves no
+    // error in the load's own report; the ImportError carries everything recorded so far
+    return report.fork().failWith(CATEGORY[code] ?? "unsupported", code, message, undefined, params, params);
+}
+/**
+ * Raise a source error outside a load (registration, a credential factory).
+ * @param code - the code
+ * @param message - a plain-ASCII message, for logs
+ * @param params - the issue's values
+ * @param format - the report's format name
+ */
+export function failAlone(code, message, params, format = "source") {
+    failOn(new ImportReportBuilder(format, 0), code, message, params);
+}
+/**
+ * Record a source warning on a report.
+ * @param report - the report
+ * @param code - the code
+ * @param message - a plain-ASCII message, for logs
+ * @param params - the issue's values
+ */
+export function warnOn(report, code, message, params) {
+    report.warning("unsupported", code, message, undefined, params);
+}
+//# sourceMappingURL=fail.js.map

package/dist/src/sources/fail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail.js","sourceRoot":"","sources":["../../../src/sources/fail.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAI1D,6CAA6C;AAC7C,MAAM,QAAQ,GAA8D;IACxE,cAAc,EAAE,kBAAkB;IAClC,gBAAgB,EAAE,kBAAkB;IACpC,iBAAiB,EAAE,aAAa;IAChC,oBAAoB,EAAE,aAAa;IACnC,kBAAkB,EAAE,eAAe;IACnC,gBAAgB,EAAE,eAAe;CACpC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAClB,MAA2B,EAC3B,IAAqB,EACrB,OAAe,EACf,MAAyC;IAEzC,6FAA6F;IAC7F,qFAAqF;IACrF,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC7G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACrB,IAAqB,EACrB,OAAe,EACf,MAAyC,EACzC,MAAM,GAAG,QAAQ;IAEjB,MAAM,CAAC,IAAI,mBAAmB,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAClB,MAA2B,EAC3B,IAAqB,EACrB,OAAe,EACf,MAAyC;IAEzC,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC"}