@graphty/graph-io 0.3.47 → 0.3.48

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

@@ -0,0 +1,362 @@
+/**
+ * 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.
+ */
+import { parseSelector } from "./selectors.js";
+import { templateNames } from "./templates.js";
+/**
+ * Whether a value is a plain object.
+ * @param v - the value
+ * @returns true for an object that is not an array
+ */
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Check a selector field.
+ * @param value - the field
+ * @param at - where it is
+ * @param push - the accumulator
+ * @param required - whether it must be present
+ * @param index - whether `#` (the record's position) is allowed
+ */
+function checkSelector(value, at, push, required, index = false) {
+    if (value === undefined && !required) {
+        return;
+    }
+    if (typeof value !== "string") {
+        push("missing", at);
+    }
+    else if (!(index && value === "#") && parseSelector(value) === null) {
+        push("selector", at);
+    }
+}
+/**
+ * Check a template field.
+ * @param value - the field
+ * @param at - where it is
+ * @param push - the accumulator
+ */
+function checkTemplate(value, at, push) {
+    if (typeof value !== "string") {
+        push("missing", at);
+    }
+    else if (templateNames(value) === null) {
+        push("template", at);
+    }
+}
+/**
+ * Check a request's query templates.
+ * @param query - the query field
+ * @param at - where the request is
+ * @param push - the accumulator
+ */
+function checkQuery(query, at, push) {
+    if (query === undefined) {
+        return;
+    }
+    if (!isObject(query)) {
+        push("missing", `${at}.query`);
+        return;
+    }
+    for (const [k, v] of Object.entries(query)) {
+        checkTemplate(v, `${at}.query.${k}`, push);
+    }
+}
+/**
+ * Whether a batch field is well formed: a positive integer max and a string join.
+ * @param batch - the batch field
+ * @returns true when it is
+ */
+function isBatch(batch) {
+    return isObject(batch) && Number.isInteger(batch.max) && batch.max >= 1 && typeof batch.join === "string";
+}
+/**
+ * Check one request.
+ * @param r - the request
+ * @param at - where it is
+ * @param entities - the mapping's entity names
+ * @param push - the accumulator
+ */
+function checkRequest(r, at, entities, push) {
+    if (!isObject(r)) {
+        push("missing", at);
+        return;
+    }
+    if (r.method !== undefined && r.method !== "GET" && r.method !== "POST") {
+        push("missing", `${at}.method`);
+    }
+    checkTemplate(r.path, `${at}.path`, push);
+    if (typeof r.path === "string" && !r.path.startsWith("/")) {
+        push("template", `${at}.path`);
+    }
+    checkQuery(r.query, at, push);
+    checkSelector(r.records, `${at}.records`, push, true);
+    if (typeof r.entity !== "string") {
+        push("missing", `${at}.entity`);
+    }
+    else if (!entities.has(r.entity)) {
+        push("unknown-entity", `${at}.entity`);
+    }
+    if (r.batch !== undefined && !isBatch(r.batch)) {
+        push("batch", `${at}.batch`);
+    }
+    if (r.paging !== undefined) {
+        checkPaging(r.paging, `${at}.paging`, push);
+    }
+}
+/**
+ * Check a paging field.
+ * @param p - the paging
+ * @param at - where it is
+ * @param push - the accumulator
+ */
+function checkPaging(p, at, push) {
+    const paging = p;
+    if (!isObject(paging)) {
+        push("paging", at);
+        return;
+    }
+    switch (paging.style) {
+        case "cursor":
+            if (typeof paging.param !== "string" || typeof paging.first !== "string") {
+                push("paging", at);
+            }
+            checkSelector(paging.next, `${at}.next`, push, true);
+            break;
+        case "offset": {
+            const size = paging.size;
+            const ok = typeof paging.param === "string" &&
+                isObject(size) &&
+                typeof size.param === "string" &&
+                Number.isInteger(size.value) &&
+                size.value > 0 &&
+                (paging.unit === undefined || paging.unit === "items" || paging.unit === "pages") &&
+                (paging.base === undefined || paging.base === 0 || paging.base === 1);
+            if (!ok) {
+                push("paging", at);
+            }
+            break;
+        }
+        case "link-header":
+            if (paging.rel !== undefined && typeof paging.rel !== "string") {
+                push("paging", at);
+            }
+            break;
+        case "next-url":
+            checkSelector(paging.next, `${at}.next`, push, true);
+            break;
+        default:
+            push("paging", `${at}.style`);
+    }
+}
+/**
+ * Check one edge rule.
+ * @param rule - the rule
+ * @param at - where it is
+ * @param entities - the mapping's entity names
+ * @param push - the accumulator
+ */
+function checkEdgeRule(rule, at, entities, push) {
+    if (!isObject(rule)) {
+        push("missing", at);
+        return;
+    }
+    const r = rule;
+    if (typeof r.type !== "string") {
+        push("missing", `${at}.type`);
+    }
+    checkSelector(r.each, `${at}.each`, push, false);
+    if ("pairs" in r) {
+        checkSelector(r.pairs, `${at}.pairs`, push, true);
+    }
+    else {
+        checkSelector(r.to, `${at}.to`, push, true);
+        checkSelector(r.from, `${at}.from`, push, false);
+        if (isObject(r.fields)) {
+            for (const [k, v] of Object.entries(r.fields)) {
+                checkSelector(v, `${at}.fields.${k}`, push, true);
+            }
+        }
+        else if (r.fields !== undefined) {
+            push("missing", `${at}.fields`);
+        }
+    }
+    if (r.entity !== undefined && (typeof r.entity !== "string" || !entities.has(r.entity))) {
+        push("unknown-entity", `${at}.entity`);
+    }
+}
+/**
+ * Check one entity.
+ * @param e - the entity
+ * @param at - where it is
+ * @param entities - the mapping's entity names
+ * @param push - the accumulator
+ */
+function checkEntity(e, at, entities, push) {
+    if (!isObject(e)) {
+        push("missing", at);
+        return;
+    }
+    checkSelector(e.id, `${at}.id`, push, true, true);
+    if (e.stripPrefix !== undefined && typeof e.stripPrefix !== "string") {
+        push("missing", `${at}.stripPrefix`);
+    }
+    if (e.label !== undefined && typeof e.label !== "string") {
+        push("missing", `${at}.label`);
+    }
+    if (e.node !== undefined && e.node) {
+        push("missing", `${at}.node`);
+    }
+    if (isObject(e.fields)) {
+        for (const [k, v] of Object.entries(e.fields)) {
+            checkSelector(v, `${at}.fields.${k}`, push, true, true);
+        }
+    }
+    else if (e.fields !== undefined) {
+        push("missing", `${at}.fields`);
+    }
+    if (Array.isArray(e.edges)) {
+        e.edges.forEach((rule, i) => {
+            checkEdgeRule(rule, `${at}.edges.${String(i)}`, entities, push);
+        });
+    }
+    else if (e.edges !== undefined) {
+        push("missing", `${at}.edges`);
+    }
+    if (Array.isArray(e.embedded)) {
+        e.embedded.forEach((em, i) => {
+            const where = `${at}.embedded.${String(i)}`;
+            if (!isObject(em)) {
+                push("missing", where);
+                return;
+            }
+            checkSelector(em.at, `${where}.at`, push, true);
+            if (typeof em.entity !== "string" || !entities.has(em.entity)) {
+                push("unknown-entity", `${where}.entity`);
+            }
+        });
+    }
+    else if (e.embedded !== undefined) {
+        push("missing", `${at}.embedded`);
+    }
+}
+/**
+ * Check the mapping's top-level names of requests.
+ * @param m - the mapping
+ * @param requests - its request names
+ * @param push - the accumulator
+ */
+function checkRequestNames(m, requests, push) {
+    const names = [
+        ["load", m.load],
+        ["hydrate", m.hydrate],
+        ["seed", m.seed],
+    ];
+    if (isObject(m.expand)) {
+        names.push(["expand.in", m.expand.in], ["expand.out", m.expand.out]);
+    }
+    else {
+        names.push(["expand", m.expand]);
+    }
+    for (const [at, name] of names) {
+        if (name === undefined && at !== "load") {
+            continue;
+        }
+        if (typeof name !== "string") {
+            push("missing", at);
+        }
+        else if (!requests.has(name)) {
+            push("unknown-request", at);
+        }
+    }
+}
+/**
+ * Check the endpoint.
+ * @param endpoint - the field
+ * @param push - the accumulator
+ */
+function checkEndpoint(endpoint, push) {
+    let url = null;
+    try {
+        url = new URL(typeof endpoint === "string" ? endpoint : "");
+    }
+    catch {
+        // not a URL
+    }
+    if (url === null ||
+        (url.protocol !== "https:" && url.protocol !== "http:") ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.search !== "" ||
+        url.hash !== "") {
+        push("endpoint", "endpoint");
+    }
+}
+/**
+ * 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 function checkRestMapping(mapping) {
+    const issues = [];
+    const push = (code, at) => {
+        issues.push(Object.freeze({ code, at }));
+    };
+    if (!isObject(mapping)) {
+        push("missing", "");
+        return issues;
+    }
+    const m = mapping;
+    if (m.version !== 1) {
+        push("version", "version");
+    }
+    checkEndpoint(m.endpoint, push);
+    const requests = isObject(m.requests) ? m.requests : {};
+    const entities = isObject(m.entities) ? m.entities : {};
+    if (!isObject(m.requests)) {
+        push("missing", "requests");
+    }
+    if (!isObject(m.entities)) {
+        push("missing", "entities");
+    }
+    const entityNames = new Set(Object.keys(entities));
+    for (const [name, r] of Object.entries(requests)) {
+        checkRequest(r, `requests.${name}`, entityNames, push);
+    }
+    for (const [name, e] of Object.entries(entities)) {
+        checkEntity(e, `entities.${name}`, entityNames, push);
+    }
+    checkRequestNames(m, new Set(Object.keys(requests)), push);
+    checkLimits(m, push);
+    checkSelector(m.modified, "modified", push, false);
+    if (m.directed !== undefined && typeof m.directed !== "boolean") {
+        push("missing", "directed");
+    }
+    return issues;
+}
+/**
+ * Check the rate limit and the budget headers.
+ * @param m - the mapping
+ * @param push - the accumulator
+ */
+function checkLimits(m, push) {
+    for (const [at, value] of [
+        ["rateLimit.requests", m.rateLimit?.requests],
+        ["rateLimit.perMs", m.rateLimit?.perMs],
+    ]) {
+        if (m.rateLimit !== undefined && !(typeof value === "number" && value > 0)) {
+            push("number", at);
+        }
+    }
+    if (m.budgetHeaders !== undefined &&
+        (typeof m.budgetHeaders.remaining !== "string" ||
+            (m.budgetHeaders.reset !== undefined && typeof m.budgetHeaders.reset !== "string"))) {
+        push("missing", "budgetHeaders");
+    }
+}
+//# sourceMappingURL=mapping.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../../../../src/sources/rest/mapping.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAiC/C;;;;GAIG;AACH,SAAS,QAAQ,CAAC,CAAU;IACxB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,KAAc,EAAE,EAAU,EAAE,IAAU,EAAE,QAAiB,EAAE,KAAK,GAAG,KAAK;IAC3F,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnC,OAAO;IACX,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;SAAM,IAAI,CAAC,CAAC,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;QACpE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACzB,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAc,EAAE,EAAU,EAAE,IAAU;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;SAAM,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACzB,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,KAA2B,EAAE,EAAU,EAAE,IAAU;IACnE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO;IACX,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC/B,OAAO;IACX,CAAC;IACD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,KAA2B;IACxC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC9G,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,CAAc,EAAE,EAAU,EAAE,QAA6B,EAAE,IAAU;IACvF,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACf,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACpB,OAAO;IACX,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACtE,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;IACD,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC1C,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IACD,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9B,aAAa,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACtD,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;SAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,gBAAgB,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,CAAwB,EAAE,EAAU,EAAE,IAAU;IACjE,MAAM,MAAM,GAAG,CAAwC,CAAC;IACxD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACnB,OAAO;IACX,CAAC;IACD,QAAQ,MAAM,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,QAAQ;YACT,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACvE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACvB,CAAC;YACD,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACrD,MAAM;QACV,KAAK,QAAQ,CAAC,CAAC,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,CAAC,IAA2C,CAAC;YAChE,MAAM,EAAE,GACJ,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;gBAChC,QAAQ,CAAC,IAAI,CAAC;gBACd,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;gBAC9B,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;gBAC3B,IAAI,CAAC,KAAgB,GAAG,CAAC;gBAC1B,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;gBACjF,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC;YAC1E,IAAI,CAAC,EAAE,EAAE,CAAC;gBACN,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACvB,CAAC;YACD,MAAM;QACV,CAAC;QACD,KAAK,aAAa;YACd,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC7D,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACvB,CAAC;YACD,MAAM;QACV,KAAK,UAAU;YACX,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACrD,MAAM;QACV;YACI,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,IAAkB,EAAE,EAAU,EAAE,QAA6B,EAAE,IAAU;IAC5F,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACpB,OAAO;IACX,CAAC;IACD,MAAM,CAAC,GAAG,IAA+B,CAAC;IAC1C,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACjD,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACf,aAAa,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACJ,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5C,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;YACrB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5C,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACtD,CAAC;QACL,CAAC;aAAM,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;QACpC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QACtF,IAAI,CAAC,gBAAgB,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,CAAa,EAAE,EAAU,EAAE,QAA6B,EAAE,IAAU;IACrF,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACf,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACpB,OAAO;IACX,CAAC;IACD,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QACnE,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvD,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACrB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5C,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;SAAM,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,CAAC,CAAC,KAAiC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YACrD,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;IACP,CAAC;SAAM,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;YACzB,MAAM,KAAK,GAAG,GAAG,EAAE,aAAa,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChB,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;gBACvB,OAAO;YACX,CAAC;YACD,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAChD,IAAI,OAAO,EAAE,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5D,IAAI,CAAC,gBAAgB,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC;YAC9C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;SAAM,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;IACtC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,CAAc,EAAE,QAA6B,EAAE,IAAU;IAChF,MAAM,KAAK,GAAwB;QAC/B,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC;QAChB,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC;QACtB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC;KACnB,CAAC;IACF,IAAI,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACzE,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;QAC7B,IAAI,IAAI,KAAK,SAAS,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;YACtC,SAAS;QACb,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACxB,CAAC;aAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAChC,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,QAAiB,EAAE,IAAU;IAChD,IAAI,GAAG,GAAe,IAAI,CAAC;IAC3B,IAAI,CAAC;QACD,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACL,YAAY;IAChB,CAAC;IACD,IACI,GAAG,KAAK,IAAI;QACZ,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC;QACvD,GAAG,CAAC,QAAQ,KAAK,EAAE;QACnB,GAAG,CAAC,QAAQ,KAAK,EAAE;QACnB,GAAG,CAAC,MAAM,KAAK,EAAE;QACjB,GAAG,CAAC,IAAI,KAAK,EAAE,EACjB,CAAC;QACC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACjC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC7C,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,MAAM,IAAI,GAAS,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE;QAC5B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACpB,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,MAAM,CAAC,GAAG,OAAiC,CAAC;IAC5C,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/B,CAAC;IACD,aAAa,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/C,YAAY,CAAC,CAAC,EAAE,YAAY,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/C,WAAW,CAAC,CAAC,EAAE,YAAY,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IACD,iBAAiB,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3D,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACrB,aAAa,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACnD,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC9D,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,CAAc,EAAE,IAAU;IAC3C,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI;QACtB,CAAC,oBAAoB,EAAE,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC;QAC7C,CAAC,iBAAiB,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC;KACjC,EAAE,CAAC;QACT,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACvB,CAAC;IACL,CAAC;IACD,IACI,CAAC,CAAC,aAAa,KAAK,SAAS;QAC7B,CAAC,OAAO,CAAC,CAAC,aAAa,CAAC,SAAS,KAAK,QAAQ;YAC1C,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,aAAa,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,EACzF,CAAC;QACC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IACrC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,27 @@
+/**
+ * The `openalex` preset of the REST mapping (design section 13.3): OpenAlex's citation graph
+ * around a work, or its co-authorship graph around an author, as a mapping the generic engine runs.
+ * The seed's own record comes first; citing works page by cursor; referenced works are stubs until
+ * hydrated or expanded. Freshness is the newest `updated_date`.
+ */
+import { type GraphSource } from "../types.js";
+import { type OpenAlexParams, type RestMapping } from "./params.js";
+/**
+ * OpenAlex's citation graph as a mapping: the seed work (`{ids}`), the works citing it page by page,
+ * each work's references as `cites` edges, and, when `{select}` asks for `authorships` and
+ * `topics`, the authors, their institutions and the topics as nodes. Fill `{ids}` with work ids
+ * and `{select}` with the fields to read. The `openalex` source chooses both from its params and
+ * leaves out the rules for what is not included. Experimental.
+ * @category Network sources
+ */
+export declare const OPENALEX_MAPPING: RestMapping;
+/**
+ * The OpenAlex preset (https://openalex.org): `work` (the citation graph around a work, default)
+ * or `author` (the works they wrote), `graph: "coauthorship"` for authors joined by shared works,
+ * and `include` (`"authors"`, `"institutions"`, `"topics"`) for more node kinds. Without a key,
+ * the first page loads and a later one warns W_SOURCE_AUTH with `report.source.next`; pass
+ * `credentials.apiKey({ query: "api_key" }, key)` and continue with the cursor. Experimental.
+ * @category Network sources
+ */
+export declare const openalexSource: GraphSource<OpenAlexParams>;
+//# sourceMappingURL=openalex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openalex.d.ts","sourceRoot":"","sources":["../../../../src/sources/rest/openalex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,KAAK,WAAW,EAAsB,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,KAAK,cAAc,EAAmB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AA8BrF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAwD7B,CAAC;AA8JH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,cAAc,CAerD,CAAC"}

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

@@ -0,0 +1,269 @@
+/**
+ * The `openalex` preset of the REST mapping (design section 13.3): OpenAlex's citation graph
+ * around a work, or its co-authorship graph around an author, as a mapping the generic engine runs.
+ * The seed's own record comes first; citing works page by cursor; referenced works are stubs until
+ * hydrated or expanded. Freshness is the newest `updated_date`.
+ */
+import { defineSource } from "../define.js";
+import { failOn } from "../fail.js";
+import { OPENALEX_SOURCE_ID } from "../ids.js";
+import { OPENALEX_DESCRIPTOR } from "./descriptor.js";
+import { restMethods } from "./source.js";
+/** OpenAlex ids are URLs under this prefix. */
+const PREFIX = "https://openalex.org/";
+/** The work fields every citation load selects. */
+const WORK_FIELDS = "id,display_name,publication_year,cited_by_count,updated_date,referenced_works";
+/**
+ * A list request over works, `{ids}` batched 50 at a time and joined by `|`.
+ * @param filter - the filter template
+ * @param perPage - the page size
+ * @param paged - whether it pages by cursor
+ * @returns the request
+ */
+function works(filter, perPage, paged) {
+    return {
+        path: "/works",
+        query: { filter, "per-page": perPage, select: "{select}" },
+        batch: { max: 50, join: "|" },
+        records: "results",
+        entity: "work",
+        ...(paged ? { paging: { style: "cursor", param: "cursor", first: "*", next: "meta.next_cursor" } } : {}),
+    };
+}
+/** An entity known by its OpenAlex id and display name. */
+const named = { id: "id", stripPrefix: PREFIX, fields: { name: "display_name" } };
+/**
+ * OpenAlex's citation graph as a mapping: the seed work (`{ids}`), the works citing it page by page,
+ * each work's references as `cites` edges, and, when `{select}` asks for `authorships` and
+ * `topics`, the authors, their institutions and the topics as nodes. Fill `{ids}` with work ids
+ * and `{select}` with the fields to read. The `openalex` source chooses both from its params and
+ * leaves out the rules for what is not included. Experimental.
+ * @category Network sources
+ */
+export const OPENALEX_MAPPING = Object.freeze({
+    version: 1,
+    endpoint: "https://api.openalex.org",
+    load: "citing",
+    seed: "by-id",
+    expand: { in: "citing", out: "by-id" },
+    hydrate: "by-id",
+    directed: true,
+    modified: "updated_date",
+    auth: { kind: "api-key", query: "api_key" },
+    rateLimit: { requests: 10, perMs: 1000 },
+    budgetHeaders: { remaining: "x-ratelimit-remaining", reset: "x-ratelimit-reset" },
+    requests: {
+        citing: works("cites:{ids}", "200", true),
+        "by-id": works("openalex:{ids}", "50", false),
+        authored: works("authorships.author.id:{ids}", "200", true),
+        "authors-by-id": {
+            path: "/authors",
+            query: { filter: "openalex:{ids}", "per-page": "50", select: "id,display_name" },
+            batch: { max: 50, join: "|" },
+            records: "results",
+            entity: "author",
+        },
+    },
+    entities: {
+        work: {
+            id: "id",
+            stripPrefix: PREFIX,
+            fields: {
+                title: "display_name",
+                year: "publication_year",
+                citedBy: "cited_by_count",
+                updated: "updated_date",
+            },
+            edges: [
+                { to: "referenced_works[]", type: "cites", entity: "work" },
+                { to: "authorships[].author.id", type: "authored_by", entity: "author" },
+                {
+                    each: "authorships[]",
+                    from: "author.id",
+                    to: "institutions[].id",
+                    type: "affiliated_with",
+                    entity: "institution",
+                },
+                { to: "topics[].id", type: "has_topic", entity: "topic" },
+            ],
+            embedded: [
+                { at: "authorships[].author", entity: "author" },
+                { at: "authorships[].institutions[]", entity: "institution" },
+                { at: "topics[]", entity: "topic" },
+            ],
+        },
+        author: named,
+        institution: named,
+        topic: named,
+    },
+});
+/**
+ * The included kinds, from an array or a comma-separated string.
+ * @param include - the param
+ * @returns the set
+ */
+function includes(include) {
+    const list = typeof include === "string" ? include.split(",") : [];
+    if (Array.isArray(include)) {
+        list.push(...include);
+    }
+    const out = new Set(list.map((v) => String(v).trim()).filter((v) => v !== ""));
+    if (out.has("institutions")) {
+        // an institution hangs off an author, so it brings its authors
+        out.add("authors");
+    }
+    return out;
+}
+/**
+ * The citation mapping without the rules for what is not included.
+ * @param include - what is included
+ * @returns the mapping
+ */
+function citationMapping(include) {
+    const { work } = OPENALEX_MAPPING.entities;
+    const keepEdge = (type) => type === "cites" ||
+        (type === "authored_by" && include.has("authors")) ||
+        (type === "affiliated_with" && include.has("institutions")) ||
+        (type === "has_topic" && include.has("topics"));
+    const keepEmbedded = (entity) => include.has(`${entity}s`);
+    return {
+        ...OPENALEX_MAPPING,
+        entities: {
+            ...OPENALEX_MAPPING.entities,
+            work: {
+                ...work,
+                edges: work.edges?.filter((e) => keepEdge(e.type)),
+                embedded: work.embedded?.filter((e) => keepEmbedded(e.entity)),
+            },
+        },
+    };
+}
+/**
+ * The co-authorship mapping: works are containers, every two authors of one work are joined by a
+ * `coauthor` edge, and an author expands through the works they wrote.
+ * @param include - what is included
+ * @param seedIsWork - whether the load starts from a work
+ * @returns the mapping
+ */
+function coauthorshipMapping(include, seedIsWork) {
+    const institutions = include.has("institutions");
+    return {
+        ...OPENALEX_MAPPING,
+        load: seedIsWork ? "by-id" : "authored",
+        seed: undefined,
+        expand: "authored",
+        hydrate: "authors-by-id",
+        directed: false,
+        entities: {
+            ...OPENALEX_MAPPING.entities,
+            work: {
+                id: "id",
+                // a rule's `from` is read with the record's own prefix
+                stripPrefix: PREFIX,
+                node: false,
+                edges: [
+                    { pairs: "authorships[].author.id", type: "coauthor", entity: "author" },
+                    ...(institutions
+                        ? [
+                            {
+                                each: "authorships[]",
+                                from: "author.id",
+                                to: "institutions[].id",
+                                type: "affiliated_with",
+                                entity: "institution",
+                            },
+                        ]
+                        : []),
+                ],
+                embedded: [
+                    { at: "authorships[].author", entity: "author" },
+                    ...(institutions ? [{ at: "authorships[].institutions[]", entity: "institution" }] : []),
+                ],
+            },
+        },
+    };
+}
+/**
+ * An OpenAlex id param: `W123` or its URL form, checked so a value cannot add a filter.
+ * @param value - the param
+ * @param name - its name
+ * @param letter - the id's kind letter
+ * @param ctx - the context
+ * @returns the bare id
+ */
+function openalexId(value, name, letter, ctx) {
+    const text = typeof value === "string" ? value.trim().replace(PREFIX, "") : "";
+    if (!new RegExp(String.raw `^${letter}\d+$`, "i").test(text)) {
+        failOn(ctx.report, "E_SOURCE_PARAM", `${name} is not an OpenAlex id`, { name, reason: "format" });
+    }
+    return text.toUpperCase();
+}
+/**
+ * The plan of an OpenAlex call.
+ * @param params - the params
+ * @param ctx - the context
+ * @param purpose - what the plan is for
+ * @returns the mapping and values
+ */
+function plan(params, ctx, purpose) {
+    const graph = params.graph ?? "citation";
+    const include = includes(params.include);
+    const hasWork = params.work !== undefined && params.work !== "";
+    const hasAuthor = params.author !== undefined && params.author !== "";
+    if (purpose !== "expand" && hasWork === hasAuthor) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "give exactly one of work and author", {
+            name: "work",
+            reason: hasWork ? "exclusive" : "required",
+        });
+    }
+    let seed = "";
+    if (hasWork) {
+        seed = openalexId(params.work, "work", "W", ctx);
+    }
+    else if (hasAuthor) {
+        seed = openalexId(params.author, "author", "A", ctx);
+    }
+    if (graph === "coauthorship") {
+        return {
+            mapping: coauthorshipMapping(include, hasWork),
+            values: { ids: seed, select: purpose === "validate" ? "id,updated_date" : "id,updated_date,authorships" },
+        };
+    }
+    let select = WORK_FIELDS + (include.has("authors") ? ",authorships" : "") + (include.has("topics") ? ",topics" : "");
+    if (purpose === "validate") {
+        select = "id,updated_date";
+    }
+    const mapping = citationMapping(include);
+    return {
+        mapping: hasWork ? mapping : { ...mapping, load: "authored", seed: undefined },
+        values: { ids: seed, select },
+    };
+}
+/** OpenAlex's own ids: a kind letter and digits. */
+const ANY_ID = /^[WAIT]\d+$/;
+const methods = restMethods(plan, false);
+/**
+ * The OpenAlex preset (https://openalex.org): `work` (the citation graph around a work, default)
+ * or `author` (the works they wrote), `graph: "coauthorship"` for authors joined by shared works,
+ * and `include` (`"authors"`, `"institutions"`, `"topics"`) for more node kinds. Without a key,
+ * the first page loads and a later one warns W_SOURCE_AUTH with `report.source.next`; pass
+ * `credentials.apiKey({ query: "api_key" }, key)` and continue with the cursor. Experimental.
+ * @category Network sources
+ */
+export const openalexSource = defineSource({
+    id: OPENALEX_SOURCE_ID,
+    descriptor: OPENALEX_DESCRIPTOR,
+    ...methods,
+    expand(request, sink, ctx) {
+        for (const id of request.ids) {
+            if (!ANY_ID.test(String(id))) {
+                failOn(ctx.report, "E_SOURCE_PARAM", "an expansion seed is not an OpenAlex id", {
+                    name: "ids",
+                    reason: "format",
+                });
+            }
+        }
+        return methods.expand(request, sink, ctx);
+    },
+});
+//# sourceMappingURL=openalex.js.map