@graphty/graph-io 0.3.46 → 0.3.48

package/src/sources/ndex/index.ts

@@ -0,0 +1,235 @@
+/**
+ * `@graphty/graph-io/sources/ndex`: the NDEx source (design section 12.1). Experimental.
+ *
+ * - load: the network's summary first (counts, download size, modification time), checked against
+ *   the caps before a byte of the network is read; then the CX2 (or CX) download, streamed into
+ *   the CX2 (or CX) importer.
+ * - probe: the summary. list: NDEx's v2 network search. validate: the summary's modificationTime.
+ * - expand: NDEx's neighborhood query (`expand.ts`).
+ *
+ * Errors are classified by status; a body is read only from a 401, 403 or 404 (NDEx's own
+ * `errorCode`, passed through as `serverCode`), so a 500 with a Java stack trace never reaches a
+ * report.
+ * @module @graphty/graph-io/sources/ndex
+ */
+
+import { defineSource } from "../define.js";
+import { failOn } from "../fail.js";
+import { NDEX_SOURCE_ID } from "../ids.js";
+import {
+    type GraphSource,
+    type SourceContext,
+    type SourceFreshness,
+    type SourceListing,
+    type SourceListQuery,
+    type SourceProbe,
+    type SourceValidators,
+} from "../types.js";
+import { checkedUuid, checkEndpoint, ndexFetch } from "./client.js";
+import { NDEX_DESCRIPTOR } from "./descriptor.js";
+import { expandNdex } from "./expand.js";
+import { type NdexParams } from "./params.js";
+
+export { NDEX_DESCRIPTOR } from "./descriptor.js";
+export { type NdexParams } from "./params.js";
+export { type NdexShareLink, parseShareUrl } from "./share-url.js";
+
+/** The fields of a network summary this source reads. */
+interface NdexSummary {
+    readonly nodeCount?: number;
+    readonly edgeCount?: number;
+    readonly cxFileSize?: number;
+    readonly cx2FileSize?: number;
+    readonly modificationTime?: number;
+    readonly creationTime?: number;
+    readonly visibility?: string;
+    readonly properties?: Readonly<Record<string, { readonly v?: unknown } | undefined>>;
+}
+
+/** One network of a v2 search answer. */
+interface NdexSearchHit {
+    readonly externalId?: string;
+    readonly name?: string;
+    readonly nodeCount?: number;
+    readonly edgeCount?: number;
+    readonly modificationTime?: number;
+}
+
+/**
+ * Read a network's summary.
+ * @param uuid - the checked UUID
+ * @param ctx - the context
+ * @returns the summary and the bytes it took
+ */
+async function readSummary(uuid: string, ctx: SourceContext): Promise<{ summary: NdexSummary; bytes: number }> {
+    const response = await ndexFetch(ctx, `v3/networks/${uuid}/summary`, uuid, {
+        headers: { Accept: "application/json" },
+    });
+    const text = await response.text();
+    try {
+        return { summary: JSON.parse(text) as NdexSummary, bytes: new TextEncoder().encode(text).byteLength };
+    } catch {
+        return failOn(ctx.report, "E_SOURCE_RESPONSE", "the NDEx summary is not JSON", {
+            expected: "json",
+            contentType: response.headers.get("content-type"),
+        });
+    }
+}
+
+/**
+ * An NDEx time (epoch milliseconds) as an ISO string.
+ * @param ms - the time
+ * @returns the ISO string, or undefined
+ */
+function iso(ms: number | undefined): string | undefined {
+    return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+}
+
+/**
+ * The download size the summary gives for a format.
+ * @param summary - the summary
+ * @param format - "cx2" or "cx"
+ * @returns the size in bytes, or undefined
+ */
+function sizeOf(summary: NdexSummary, format: string): number | undefined {
+    return format === "cx" ? summary.cxFileSize : summary.cx2FileSize;
+}
+
+/**
+ * Stop the load before its first byte when the summary says a cap would cut it: a network file cut
+ * short is not a graph, so this is E_SOURCE_LIMIT under either `onLimit`.
+ * @param summary - the summary
+ * @param format - the download format
+ * @param ctx - the context
+ */
+function checkCaps(summary: NdexSummary, format: string, ctx: SourceContext): void {
+    const caps: [string, number | undefined, number | undefined][] = [
+        ["maxNodes", summary.nodeCount, ctx.limits.maxNodes],
+        ["maxEdges", summary.edgeCount, ctx.limits.maxEdges],
+        ["maxBytes", sizeOf(summary, format), ctx.limits.maxBytes],
+    ];
+    for (const [limit, value, cap] of caps) {
+        if (value !== undefined && cap !== undefined && value > cap) {
+            failOn(ctx.report, "E_SOURCE_LIMIT", `the network's ${limit} of ${String(value)} is over the cap`, {
+                limit,
+                value,
+            });
+        }
+    }
+}
+
+/**
+ * The graph facts a summary adds: when it changed, and who may use it.
+ * @param summary - the summary
+ * @returns the facts
+ */
+function metaOf(summary: NdexSummary): Record<string, string> {
+    const meta: Record<string, string> = {};
+    const modified = iso(summary.modificationTime);
+    if (modified !== undefined) {
+        meta.modified = modified;
+    }
+    if (typeof summary.visibility === "string") {
+        meta.visibility = summary.visibility;
+    }
+    for (const key of ["rights", "rightsHolder"]) {
+        const value = summary.properties?.[key]?.v;
+        if (typeof value === "string") {
+            meta[key] = value;
+        }
+    }
+    return meta;
+}
+
+/**
+ * The validators of a summary.
+ * @param summary - the summary
+ * @returns `{ modified }` when NDEx gave a modification time
+ */
+function validatorsOf(summary: NdexSummary): SourceValidators {
+    const modified = iso(summary.modificationTime);
+    return modified === undefined ? {} : { modified };
+}
+
+/**
+ * The NDEx source. Experimental.
+ * @category Network sources
+ */
+export const ndexSource: GraphSource<NdexParams> = defineSource<NdexParams>({
+    id: NDEX_SOURCE_ID,
+    descriptor: NDEX_DESCRIPTOR,
+    async file(params, ctx) {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const format = params.format ?? "cx2";
+        const { summary, bytes } = await readSummary(uuid, ctx);
+        checkCaps(summary, format, ctx);
+        const size = sizeOf(summary, format);
+        // progress counts every byte read, the summary's included
+        ctx.progress(bytes, size === undefined ? undefined : bytes + size, "bytes");
+        // records the validators in report.source; the file path keeps them
+        ctx.finish({ validators: validatorsOf(summary) });
+        const path = format === "cx" ? `v2/network/${uuid}` : `v3/networks/${uuid}`;
+        const body = await ndexFetch(ctx, path, uuid);
+        return { body, format, meta: metaOf(summary) };
+    },
+    async probe(params, ctx): Promise<SourceProbe> {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const { summary } = await readSummary(uuid, ctx);
+        return {
+            ok: true,
+            counts: {
+                nodes: summary.nodeCount,
+                edges: summary.edgeCount,
+                bytes: sizeOf(summary, params.format ?? "cx2"),
+            },
+        };
+    },
+    async list(query: SourceListQuery<NdexParams>, ctx): Promise<SourceListing> {
+        checkEndpoint(ctx);
+        const start = Number(query.cursor?.start ?? 0);
+        const size = query.size ?? 25;
+        const body = await ctx.fetchJson<{ networks?: unknown; numFound?: unknown }>(
+            `v2/search/network?start=${String(start)}&size=${String(size)}`,
+            {
+                method: "POST",
+                idempotent: true,
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ searchString: query.search ?? "" }),
+            },
+        );
+        const networks = Array.isArray(body.networks)
+            ? (body.networks as readonly NdexSearchHit[])
+            : failOn(ctx.report, "E_SOURCE_RESPONSE", "the NDEx search answer has no networks", {
+                  expected: "ndex-search",
+                  contentType: "application/json",
+              });
+        const { numFound } = body;
+        const items = networks.flatMap((n) =>
+            typeof n.externalId === "string"
+                ? [
+                      {
+                          params: { uuid: n.externalId },
+                          name: n.name ?? n.externalId,
+                          nodeCount: n.nodeCount,
+                          edgeCount: n.edgeCount,
+                          modified: iso(n.modificationTime),
+                      },
+                  ]
+                : [],
+        );
+        const total = typeof numFound === "number" ? numFound : undefined;
+        const more = total === undefined ? networks.length === size : start + networks.length < total;
+        return { items, next: more && networks.length > 0 ? { start: start + networks.length } : null, total };
+    },
+    async validate(params, seen, ctx): Promise<SourceFreshness> {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const validators = validatorsOf((await readSummary(uuid, ctx)).summary);
+        if (seen.modified === undefined || validators.modified === undefined) {
+            return { status: "unverifiable", validators };
+        }
+        return seen.modified === validators.modified
+            ? { status: "current", via: "modified", validators }
+            : { status: "changed", via: "modified", changedAt: validators.modified, validators };
+    },
+    expand: expandNdex,
+});

package/src/sources/ndex/params.ts

@@ -0,0 +1,17 @@
+/**
+ * The parameters of the NDEx source (design section 12.1). Experimental. The NDEx work may add
+ * optional fields only.
+ */
+
+/**
+ * What to load from NDEx. Experimental.
+ * @category Network sources
+ */
+export interface NdexParams {
+    /** The network's UUID ("86719f5b-1439-11f0-9806-005056ae3c32"). */
+    readonly uuid: string;
+    /** The download format. @defaultValue "cx2" */
+    readonly format?: "cx2" | "cx" | undefined;
+    /** The node attribute that identifies a node across NDEx's two id spaces (for expand): "name", "represents". */
+    readonly idAttribute?: string | undefined;
+}

package/src/sources/ndex/share-url.ts

@@ -0,0 +1,84 @@
+/**
+ * NDEx share links: a network's page or API URL, possibly carrying a link-share access key.
+ */
+
+import { credentials } from "../credentials.js";
+import { failAlone } from "../fail.js";
+import { NDEX_SOURCE_ID } from "../ids.js";
+import { type Credential } from "../types.js";
+import { ACCESS_KEY_QUERY } from "./client.js";
+
+/** A network UUID anywhere in a URL's path or hash. */
+const UUID_IN_URL = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+
+/**
+ * What a share link says: the network, the NDEx server, and the access key as a credential.
+ * Experimental.
+ * @category Network sources
+ */
+export interface NdexShareLink {
+    /** The params to load the network with. */
+    readonly params: {
+        /** The network's NDEx id. */
+        readonly uuid: string;
+    };
+    /** The NDEx server the link points at ("https://www.ndexbio.org/"). */
+    readonly endpoint: string;
+    /** The link's access key, sent only to that server; absent when the link has none. */
+    readonly credential?: Credential | undefined;
+}
+
+/**
+ * Read an NDEx share link (`https://www.ndexbio.org/viewer/networks/<uuid>?accesskey=<key>`, the
+ * older `#/network/<uuid>` form, or an API URL). The access key leaves the URL and becomes a
+ * credential bound to the link's server, so it is never logged or stored with the params.
+ * Rejects with `E_SOURCE_PARAM` (`name: "url"`): `reason: "format"` when the text is not a URL
+ * naming a network, `"credentials-in-url"` when it carries a user name or password. Experimental.
+ * @param url - the link
+ * @returns the params, endpoint and credential to load it with
+ * @example
+ * ```ts
+ * const link = parseShareUrl(sharedUrl);
+ * const { snapshot } = await loadFromSource("ndex", link.params, {
+ *     endpoint: link.endpoint,
+ *     credential: link.credential,
+ * });
+ * ```
+ * @category Network sources
+ */
+export function parseShareUrl(url: string | URL): NdexShareLink {
+    let parsed: URL;
+    try {
+        parsed = new URL(url);
+    } catch {
+        return refuse("format");
+    }
+    if (parsed.username !== "" || parsed.password !== "") {
+        return refuse("credentials-in-url");
+    }
+    // the older viewer keeps the network and its key in the hash
+    const hash = new URL(parsed.hash.replace(/^#/, ""), "https://hash.invalid/");
+    const uuid = UUID_IN_URL.exec(`${parsed.pathname} ${hash.pathname}`)?.[0];
+    if (uuid === undefined || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+        return refuse("format");
+    }
+    // the bare host redirects to www without CORS headers, so a page cannot follow it
+    const host = parsed.host.toLowerCase() === "ndexbio.org" ? "www.ndexbio.org" : parsed.host;
+    const endpoint = `${parsed.protocol}//${host}/`;
+    const key = parsed.searchParams.get(ACCESS_KEY_QUERY) ?? hash.searchParams.get(ACCESS_KEY_QUERY);
+    const params = { uuid: uuid.toLowerCase() };
+    if (key === null || key === "") {
+        return { params, endpoint };
+    }
+    const credential = credentials.apiKey({ query: ACCESS_KEY_QUERY }, key, { origins: [new URL(endpoint).origin] });
+    return { params, endpoint, credential };
+}
+
+/**
+ * Reject a share link.
+ * @param reason - why
+ * @returns never
+ */
+function refuse(reason: "format" | "credentials-in-url"): never {
+    return failAlone("E_SOURCE_PARAM", "not an NDEx share link", { name: "url", reason }, `source:${NDEX_SOURCE_ID}`);
+}

package/src/sources/params.ts

@@ -0,0 +1,29 @@
+/**
+ * `SourceParamsMap`: the params type of every built-in source by id, so `loadFromSource("ndex", ...)`
+ * type-checks its params. A consumer adds its own source by declaration merging.
+ */
+
+import { type CypherParams } from "./cypher/params.js";
+import { type NdexParams } from "./ndex/params.js";
+import { type OpenAlexParams, type RestParams } from "./rest/params.js";
+
+/**
+ * Parameter types by source id; extend it by declaration merging:
+ * `declare module "@graphty/graph-io" { interface SourceParamsMap { people: { team: string } } }`.
+ * Experimental.
+ * @category Network sources
+ */
+export interface SourceParamsMap {
+    /** NDEx. */
+    ndex: NdexParams;
+    /** Any openCypher server. */
+    cypher: CypherParams;
+    /** Neo4j. */
+    neo4j: CypherParams;
+    /** Amazon Neptune. */
+    neptune: CypherParams;
+    /** A REST API through a mapping. */
+    rest: RestParams;
+    /** OpenAlex. */
+    openalex: OpenAlexParams;
+}

package/src/sources/registry.ts

@@ -0,0 +1,325 @@
+/**
+ * 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 { type GraphBuilder, type GraphSink } from "@graphty/graph-format";
+
+import { type FormatRegistry, type ImportGraphResult } from "../registry.js";
+import { type ImportReport } from "../types.js";
+import { checkLazySource, checkSource } from "./define.js";
+import { failAlone } from "./fail.js";
+import { runIntoSink, runMethod, sourceFormat, stopAtLimit, withSource, wrapCursor, wrapSink } from "./run.js";
+import {
+    type ExpandRequest,
+    type GraphSource,
+    type LazySource,
+    type LoadFromSourceOptions,
+    type SourceDescriptor,
+    type SourceFreshness,
+    type SourceInfo,
+    type SourceListing,
+    type SourceListQuery,
+    type SourceProbe,
+    type SourceValidators,
+} from "./types.js";
+
+/** A registered source: loaded, or a lazy one with its descriptor. */
+interface Entry {
+    /** The descriptor known without loading. */
+    readonly descriptor: SourceDescriptor;
+    /** The lazy registration, if any. */
+    readonly lazy: LazySource | null;
+    /** The loaded source. */
+    source: GraphSource<never> | null;
+    /** The load in flight. */
+    loading: Promise<GraphSource<never>> | null;
+}
+
+/**
+ * Whether a registration is a lazy source rather than a source.
+ * @param value - the registration
+ * @returns true for a LazySource
+ */
+function isLazy(value: GraphSource<never> | LazySource): value is LazySource {
+    const v = value as { load?: unknown; records?: unknown; file?: unknown; import?: unknown };
+    return typeof v.load === "function" && v.records === undefined && v.file === undefined && v.import === undefined;
+}
+
+/** What a SourceRegistry borrows from its FormatRegistry: building and freezing a graph. */
+interface SourceBuilding {
+    /**
+     * A builder seeded from the load options.
+     * @param options - the options
+     * @param format - the report format name
+     * @returns the builder
+     */
+    readonly newBuilder: (options: LoadFromSourceOptions, format: string) => GraphBuilder;
+    /**
+     * Freeze a filled builder into a load result.
+     * @param format - the result's format
+     * @param builder - the builder
+     * @param report - the report
+     * @param options - the options
+     * @returns the result
+     */
+    readonly freeze: (
+        format: string,
+        builder: GraphBuilder,
+        report: ImportReport,
+        options: LoadFromSourceOptions,
+    ) => ImportGraphResult;
+}
+
+/**
+ * The sources of one FormatRegistry. Experimental.
+ * @category Network sources
+ */
+export class SourceRegistry {
+    private readonly entries = new Map<string, Entry>();
+
+    /**
+     * 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(
+        private readonly formats: FormatRegistry,
+        private readonly building: SourceBuilding,
+    ) {}
+
+    /**
+     * 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: GraphSource<never> | LazySource): void {
+        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 as GraphSource<never>) : null,
+            loading: null,
+        });
+    }
+
+    /**
+     * Whether a source id is registered.
+     * @param id - the id
+     * @returns true when registered
+     */
+    has(id: string): boolean {
+        return this.entries.has(id);
+    }
+
+    /**
+     * Every registered source, without loading any code.
+     * @returns one entry per source, in registration order
+     */
+    list(): readonly SourceInfo[] {
+        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: string | GraphSource<never>): Promise<GraphSource<never>> {
+        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 as LazySource;
+        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: unknown) => {
+                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: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        options: LoadFromSourceOptions = {},
+    ): Promise<ImportGraphResult> {
+        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: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        sink: GraphSink,
+        options: LoadFromSourceOptions = {},
+    ): Promise<ImportReport> {
+        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: string | GraphSource<never>,
+        request: ExpandRequest<Readonly<Record<string, unknown>>>,
+        options: LoadFromSourceOptions = {},
+    ): Promise<ImportGraphResult> {
+        const resolved = await this.resolve(source);
+        const builder: GraphBuilder = 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 } as never, sink, prepared.created.ctx);
+            const out = await stopAtLimit(run as Promise<ImportReport>, 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: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        options: LoadFromSourceOptions = {},
+    ): Promise<SourceProbe> {
+        const resolved = await this.resolve(source);
+        return runMethod(
+            resolved,
+            "probe",
+            params,
+            options,
+            (prepared) => resolved.probe?.(prepared.params as never, prepared.created.ctx) as Promise<SourceProbe>,
+        );
+    }
+
+    /**
+     * 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: string | GraphSource<never>,
+        query: SourceListQuery<Readonly<Record<string, unknown>>>,
+        options: LoadFromSourceOptions = {},
+    ): Promise<SourceListing> {
+        const resolved = await this.resolve(source);
+        // a search narrows by some params, so required ones are not checked
+        const partial: SourceDescriptor | undefined =
+            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 } as never,
+                    prepared.created.ctx,
+                ) as Promise<SourceListing>,
+        );
+    }
+
+    /**
+     * 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: string | GraphSource<never>,
+        params: Readonly<Record<string, unknown>>,
+        seen: SourceValidators,
+        options: LoadFromSourceOptions = {},
+    ): Promise<SourceFreshness> {
+        const resolved = await this.resolve(source);
+        return runMethod(
+            resolved,
+            "validate",
+            params,
+            options,
+            (prepared) =>
+                resolved.validate?.(prepared.params as never, seen, prepared.created.ctx) as Promise<SourceFreshness>,
+        );
+    }
+}