@graphty/graph-io 0.3.47 → 0.3.49

package/dist/src/sources/registry.js

@@ -0,0 +1,193 @@
+/**
+ * The source registry (design section 3): sources by id, in their own name space beside the
+ * formats. Lazy sources are registered by descriptor and load their code on first use, so listing
+ * sources loads none. A FormatRegistry holds one, so one object holds formats and sources.
+ */
+import { checkLazySource, checkSource } from "./define.js";
+import { failAlone } from "./fail.js";
+import { runIntoSink, runMethod, sourceFormat, stopAtLimit, withSource, wrapCursor, wrapSink } from "./run.js";
+/**
+ * Whether a registration is a lazy source rather than a source.
+ * @param value - the registration
+ * @returns true for a LazySource
+ */
+function isLazy(value) {
+    const v = value;
+    return typeof v.load === "function" && v.records === undefined && v.file === undefined && v.import === undefined;
+}
+/**
+ * The sources of one FormatRegistry. Experimental.
+ * @category Network sources
+ */
+export class SourceRegistry {
+    /**
+     * Create one for a format registry, whose importers read `file` sources.
+     * @param formats - the format registry
+     * @param building - how it builds and freezes graphs
+     */
+    constructor(formats, building) {
+        this.formats = formats;
+        this.building = building;
+        this.entries = new Map();
+    }
+    /**
+     * Register a source or a lazy source. A malformed one, or an id already taken, throws an
+     * ImportError with E_SOURCE_INVALID.
+     * @param source - the source
+     */
+    register(source) {
+        if (isLazy(source)) {
+            checkLazySource(source);
+        }
+        else {
+            checkSource(source);
+        }
+        if (this.entries.has(source.id)) {
+            failAlone("E_SOURCE_INVALID", `a source with id ${source.id} is already registered`, {
+                id: source.id,
+                reason: "duplicate",
+            });
+        }
+        const lazy = isLazy(source) ? source : null;
+        this.entries.set(source.id, {
+            descriptor: source.descriptor ?? { plainName: source.id, params: [] },
+            lazy,
+            source: lazy === null ? source : null,
+            loading: null,
+        });
+    }
+    /**
+     * Whether a source id is registered.
+     * @param id - the id
+     * @returns true when registered
+     */
+    has(id) {
+        return this.entries.has(id);
+    }
+    /**
+     * Every registered source, without loading any code.
+     * @returns one entry per source, in registration order
+     */
+    list() {
+        return Object.freeze([...this.entries].map(([id, e]) => Object.freeze({ id, descriptor: e.descriptor, loaded: e.source !== null })));
+    }
+    /**
+     * A source by id, loading a lazy one; a source object passes through after its checks.
+     * @param source - the id or the source
+     * @returns the loaded source
+     */
+    async resolve(source) {
+        if (typeof source !== "string") {
+            checkSource(source);
+            return source;
+        }
+        const entry = this.entries.get(source);
+        if (entry === undefined) {
+            return failAlone("E_SOURCE_UNKNOWN", `no source has id ${JSON.stringify(source)}`, { id: source, known: [...this.entries.keys()] }, sourceFormat(source));
+        }
+        if (entry.source !== null) {
+            return entry.source;
+        }
+        const lazy = entry.lazy;
+        entry.loading ?? (entry.loading = lazy.load().then((loaded) => {
+            if (loaded.id !== lazy.id) {
+                failAlone("E_SOURCE_INVALID", `lazy source ${lazy.id} loaded a source with id ${loaded.id}`, {
+                    id: lazy.id,
+                    reason: "lazy",
+                });
+            }
+            checkSource(loaded, lazy.descriptor);
+            entry.source = loaded.descriptor === undefined ? { ...loaded, descriptor: lazy.descriptor } : loaded;
+            return entry.source;
+        }, (err) => {
+            entry.loading = null;
+            throw err;
+        }));
+        return entry.loading;
+    }
+    /**
+     * Load a graph from a source.
+     * @param source - the id or the source
+     * @param params - its params
+     * @param options - endpoint, credential, cursor, caps and the import options
+     * @returns the graph and the report
+     */
+    async load(source, params, options = {}) {
+        const resolved = await this.resolve(source);
+        const builder = this.building.newBuilder(options, sourceFormat(resolved.id));
+        const { report, format } = await runIntoSink(resolved, params, builder, options, this.formats);
+        return this.building.freeze(format, builder, report, options);
+    }
+    /**
+     * Load from a source into a sink you own.
+     * @param source - the id or the source
+     * @param params - its params
+     * @param sink - where to write
+     * @param options - the options
+     * @returns the report
+     */
+    async import(source, params, sink, options = {}) {
+        const resolved = await this.resolve(source);
+        return (await runIntoSink(resolved, params, sink, options, this.formats)).report;
+    }
+    /**
+     * Fetch the neighborhood of some nodes: a snapshot of only what was fetched.
+     * @param source - the id or the source
+     * @param request - the seeds and how far to go
+     * @param options - the options
+     * @returns the fetched part and the report
+     */
+    async expand(source, request, options = {}) {
+        const resolved = await this.resolve(source);
+        const builder = this.building.newBuilder(options, sourceFormat(resolved.id));
+        const report = await runMethod(resolved, "expand", request.params, options, async (prepared) => {
+            const sink = wrapSink(builder, prepared, options.idPrefix);
+            const run = resolved.expand?.({ ...request, params: prepared.params }, sink, prepared.created.ctx);
+            const out = await stopAtLimit(run, prepared);
+            return withSource(out, prepared, wrapCursor(prepared.created.state.finish?.next, resolved.descriptor?.version ?? 1));
+        });
+        return this.building.freeze(sourceFormat(resolved.id), builder, report, options);
+    }
+    /**
+     * Check params and credential without loading.
+     * @param source - the id or the source
+     * @param params - its params
+     * @param options - the options
+     * @returns what the service said
+     */
+    async probe(source, params, options = {}) {
+        const resolved = await this.resolve(source);
+        return runMethod(resolved, "probe", params, options, (prepared) => resolved.probe?.(prepared.params, prepared.created.ctx));
+    }
+    /**
+     * Search what a source holds.
+     * @param source - the id or the source
+     * @param query - the search
+     * @param options - the options
+     * @returns one page of results
+     */
+    async search(source, query, options = {}) {
+        const resolved = await this.resolve(source);
+        // a search narrows by some params, so required ones are not checked
+        const partial = resolved.descriptor === undefined
+            ? undefined
+            : {
+                ...resolved.descriptor,
+                params: resolved.descriptor.params.map((p) => ({ ...p, required: false })),
+            };
+        return runMethod({ ...resolved, descriptor: partial }, "list", query.params, options, (prepared) => resolved.list?.({ ...query, params: prepared.params }, prepared.created.ctx));
+    }
+    /**
+     * Tell whether data loaded earlier changed.
+     * @param source - the id or the source
+     * @param params - the params it was loaded with
+     * @param seen - the validators recorded then
+     * @param options - the options
+     * @returns whether it changed
+     */
+    async validate(source, params, seen, options = {}) {
+        const resolved = await this.resolve(source);
+        return runMethod(resolved, "validate", params, options, (prepared) => resolved.validate?.(prepared.params, seen, prepared.created.ctx));
+    }
+}
+//# sourceMappingURL=registry.js.map

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

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

package/dist/src/sources/rest/descriptor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The descriptors of the REST mapping source and its `openalex` preset: catalog data, available
+ * without loading the sources' code.
+ */
+import { type SourceDescriptor } from "../types.js";
+/**
+ * The descriptor of the generic `rest` source. Experimental.
+ * @category Network sources
+ */
+export declare const REST_DESCRIPTOR: SourceDescriptor;
+/**
+ * The descriptor of the `openalex` preset. Experimental.
+ * @category Network sources
+ */
+export declare const OPENALEX_DESCRIPTOR: SourceDescriptor;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/src/sources/rest/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../../src/sources/rest/descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,gBAyB5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,gBAkChC,CAAC"}

package/dist/src/sources/rest/descriptor.js

@@ -0,0 +1,76 @@
+/**
+ * The descriptors of the REST mapping source and its `openalex` preset: catalog data, available
+ * without loading the sources' code.
+ */
+import { DEPS_DEV_MAPPING } from "./samples/deps-dev.js";
+import { STRING_MAPPING } from "./samples/string.js";
+/**
+ * The descriptor of the generic `rest` source. Experimental.
+ * @category Network sources
+ */
+export const REST_DESCRIPTOR = Object.freeze({
+    plainName: "REST API",
+    kind: "rest",
+    version: 1,
+    auth: ["bearer", "api-key"],
+    authRequired: "optional",
+    // ponytail: a mapping without `expand` or paging cannot do either; per-mapping features when a form needs them
+    features: ["expand", "probe", "validate", "page"],
+    params: [{ name: "mapping", plainName: "Mapping", type: "text", required: true }],
+    samples: [
+        {
+            id: "string-tp53",
+            plainName: "STRING: TP53's functional partners",
+            params: { mapping: STRING_MAPPING, identifiers: "TP53", species: "9606", add_nodes: "20" },
+            endpoint: STRING_MAPPING.endpoint,
+            counts: { nodes: 21, edges: 113 },
+        },
+        {
+            id: "deps-dev-webpack",
+            plainName: "deps.dev: webpack 5.90.0",
+            params: { mapping: DEPS_DEV_MAPPING, system: "npm", package: "webpack", version: "5.90.0" },
+            endpoint: DEPS_DEV_MAPPING.endpoint,
+            counts: { nodes: 84, edges: 121 },
+        },
+    ],
+});
+/**
+ * The descriptor of the `openalex` preset. Experimental.
+ * @category Network sources
+ */
+export const OPENALEX_DESCRIPTOR = Object.freeze({
+    plainName: "OpenAlex",
+    kind: "rest",
+    version: 1,
+    defaultEndpoint: "https://api.openalex.org",
+    auth: ["api-key"],
+    authRequired: "optional",
+    apiKey: { query: "api_key" },
+    rateLimit: { requests: 10, perMs: 1000 },
+    features: ["expand", "probe", "validate", "page"],
+    params: [
+        { name: "work", plainName: "Work", type: "string" },
+        { name: "author", plainName: "Author", type: "string" },
+        {
+            name: "graph",
+            plainName: "Graph",
+            type: "enum",
+            default: "citation",
+            values: [
+                { value: "citation", label: "Citations" },
+                { value: "coauthorship", label: "Co-authors" },
+            ],
+        },
+        { name: "include", plainName: "Include", type: "string", advanced: true },
+    ],
+    samples: [
+        {
+            id: "openalex-watts-strogatz",
+            plainName: "Watts-Strogatz paper's citations",
+            params: { work: "W2112090702" },
+            whole: false,
+            firstPage: 200,
+        },
+    ],
+});
+//# sourceMappingURL=descriptor.js.map

package/dist/src/sources/rest/descriptor.js.map

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

package/dist/src/sources/rest/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@graphty/graph-io/sources/rest`: the REST mapping source, `restSource()` for turning a mapping
+ * into a source of its own, and the `openalex` preset. Experimental: the mapping format carries
+ * `version: 1`.
+ * @module @graphty/graph-io/sources/rest
+ */
+export { OPENALEX_DESCRIPTOR, REST_DESCRIPTOR } from "./descriptor.js";
+export { checkRestMapping, type RestMappingIssue, type RestMappingIssueCode } from "./mapping.js";
+export { OPENALEX_MAPPING, openalexSource } from "./openalex.js";
+export { type OpenAlexParams, type RestEdgeRule, type RestEntity, type RestMapping, type RestPaging, type RestParams, type RestRequest, } from "./params.js";
+export { DEPS_DEV_MAPPING } from "./samples/deps-dev.js";
+export { STRING_MAPPING } from "./samples/string.js";
+export { restMappingSource, restSource, type RestSourceInfo } from "./source.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/sources/rest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/sources/rest/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,WAAW,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/sources/rest/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@graphty/graph-io/sources/rest`: the REST mapping source, `restSource()` for turning a mapping
+ * into a source of its own, and the `openalex` preset. Experimental: the mapping format carries
+ * `version: 1`.
+ * @module @graphty/graph-io/sources/rest
+ */
+export { OPENALEX_DESCRIPTOR, REST_DESCRIPTOR } from "./descriptor.js";
+export { checkRestMapping } from "./mapping.js";
+export { OPENALEX_MAPPING, openalexSource } from "./openalex.js";
+export { DEPS_DEV_MAPPING } from "./samples/deps-dev.js";
+export { STRING_MAPPING } from "./samples/string.js";
+export { restMappingSource, restSource } from "./source.js";
+//# sourceMappingURL=index.js.map

package/dist/src/sources/rest/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/sources/rest/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAoD,MAAM,cAAc,CAAC;AAClG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAUjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAuB,MAAM,aAAa,CAAC"}

package/dist/src/sources/rest/mapping.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Checking a REST mapping before it runs (design section 13.2). A mapping is JSON data, typed into
+ * a form or read from a project file, so every field is checked and every problem is a coded
+ * issue naming where it is.
+ */
+/**
+ * What is wrong with one field of a mapping. Open union.
+ * @category Network sources
+ */
+export type RestMappingIssueCode = "version" | "endpoint" | "missing" | "unknown-request" | "unknown-entity" | "selector" | "template" | "paging" | "batch" | "number" | (string & {});
+/**
+ * One problem `checkRestMapping` found. Experimental.
+ * @category Network sources
+ */
+export interface RestMappingIssue {
+    /** What is wrong. */
+    readonly code: RestMappingIssueCode;
+    /** Where, as a dotted path into the mapping (`requests.citing.paging.next`). */
+    readonly at: string;
+}
+/**
+ * Check a REST mapping without running it: the version, the endpoint, every request (templates,
+ * selectors, paging, batching) and entity (selectors, edge rules, embedded records), and that every
+ * name it uses exists. Experimental.
+ * @param mapping - the mapping, as data from anywhere
+ * @returns every problem found; empty when the mapping can run
+ * @category Network sources
+ */
+export declare function checkRestMapping(mapping: unknown): readonly RestMappingIssue[];
+//# sourceMappingURL=mapping.d.ts.map

package/dist/src/sources/rest/mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../../../../src/sources/rest/mapping.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC1B,SAAS,GACT,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,gBAAgB,GAChB,UAAU,GACV,UAAU,GACV,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACvB;AAySD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,gBAAgB,EAAE,CAoC9E"}