@shipworthy/openapi-parser 0.0.0-stage → 0.0.1

package/dist/pipeline.js

@@ -0,0 +1,446 @@
+import { JsonPointer, JsonSchema, Predicate } from "effect";
+import { getAt, joinPointer } from "./pointer.js";
+import { componentSchemas, schemaSlots } from "./upgraders/3.0-to-3.1.js";
+import { bundleFailure, circularAliasFailure, invalidPointerFailure, missingPointerFailure, } from "./errors.js";
+const ANNOTATIONS = ["example", "discriminator", "xml", "externalDocs", "nullable"];
+function asRecord(value) {
+    return Predicate.isObject(value) ? value : undefined;
+}
+const NESTED_SINGLE = [
+    "additionalProperties",
+    "unevaluatedProperties",
+    "items",
+    "contains",
+    "not",
+    "if",
+    "then",
+    "else",
+    "propertyNames",
+    "unevaluatedItems",
+    "contentSchema",
+];
+const NESTED_ARRAY = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const NESTED_MAP = ["properties", "patternProperties", "$defs", "dependentSchemas"];
+export function runSchemaPipeline(document, mode, hooks) {
+    const definitions = {};
+    const definitionOrder = [];
+    const booleanDefinitions = new Map();
+    for (const slot of componentSchemas(document)) {
+        const value = slot.parent[slot.key];
+        if (typeof value === "boolean") {
+            booleanDefinitions.set(slot.key, value);
+        }
+        const normalized = normalizeSchema(slot.parent[slot.key]);
+        definitions[slot.key] = normalized.schema;
+        rememberDefinition(definitionOrder, slot.key);
+        mergeDefinitions(definitions, normalized.definitions, normalized.schema, definitionOrder);
+    }
+    const others = schemaSlots(document, false);
+    const slotSchemas = [];
+    const booleanSlots = others.map((slot) => {
+        const value = slot.parent[slot.key];
+        return typeof value === "boolean" ? value : undefined;
+    });
+    for (const slot of others) {
+        const normalized = normalizeSchema(slot.parent[slot.key]);
+        mergeDefinitions(definitions, normalized.definitions, normalized.schema, definitionOrder);
+        slot.parent[slot.key] = normalized.schema;
+        slotSchemas.push(normalized.schema);
+    }
+    const recursive = recursiveNames(definitions);
+    const rootDefs = new Set(Object.keys(asRecord(document.$defs) ?? {}));
+    const aliases = new Map();
+    const resolving = new Set();
+    for (const name of Object.keys(definitions)) {
+        definitions[name] = resolveValue(definitions[name], definitions, rootDefs, recursive, aliases, resolving, mode, hooks, `#/$defs/${name}`);
+    }
+    for (let index = 0; index < slotSchemas.length; index++) {
+        slotSchemas[index] = resolveValue(slotSchemas[index], definitions, rootDefs, recursive, aliases, resolving, mode, hooks, "#");
+        const slot = others[index];
+        if (slot)
+            slot.parent[slot.key] = slotSchemas[index];
+    }
+    const parked = [];
+    for (const [name, schema] of Object.entries(definitions))
+        park(schema, "definition", name, [], parked);
+    slotSchemas.forEach((schema, index) => park(schema, "schema", String(index), [], parked));
+    const schemas = (slotSchemas.length > 0 ? slotSchemas : [{}]);
+    const converted = JsonSchema.toMultiDocumentOpenApi3_1({
+        dialect: "draft-2020-12",
+        schemas,
+        definitions,
+    });
+    restore(converted, parked);
+    const components = asRecord(document.components) ?? {};
+    document.components = components;
+    components.schemas = orderDefinitions(converted.definitions, definitionOrder);
+    for (const slot of componentSchemas(document)) {
+        const value = booleanDefinitions.get(slot.key);
+        if (value !== undefined)
+            slot.parent[slot.key] = value;
+    }
+    others.forEach((slot, index) => {
+        slot.parent[slot.key] = booleanSlots[index] ?? converted.schemas[index];
+    });
+    rewriteLeftoverDefinitionRefs(document);
+    restoreRootDefs(document);
+    if (mode === "dereference")
+        inlineRemaining(document, recursive, hooks);
+}
+function normalizeSchema(value) {
+    if (typeof value === "boolean") {
+        return { dialect: "draft-2020-12", schema: value ? {} : { not: {} }, definitions: {} };
+    }
+    const record = asRecord(value);
+    if (!record)
+        throw bundleFailure("A schema position must contain an object or a boolean");
+    const normalized = JsonSchema.fromSchemaOpenApi3_1(liftSiblings(record));
+    // A schema $id is its own resource, so its $defs join the shared pool.
+    // Nested $defs on a schema without $id stay on that schema.
+    if (typeof record.$id === "string")
+        return normalized;
+    const extracted = asRecord(normalized.definitions);
+    if (!extracted || Object.keys(extracted).length === 0)
+        return normalized;
+    const schema = asRecord(normalized.schema) ?? {};
+    schema.$defs = { ...asRecord(schema.$defs), ...extracted };
+    return { dialect: normalized.dialect, schema, definitions: {} };
+}
+function mergeDefinitions(pool, extra, owner, order) {
+    for (const [name, schema] of Object.entries(extra)) {
+        if (!Object.hasOwn(pool, name)) {
+            pool[name] = schema;
+            rememberDefinition(order, name);
+            continue;
+        }
+        if (JSON.stringify(pool[name]) === JSON.stringify(schema))
+            continue;
+        const unique = uniqueName(pool, name);
+        pool[unique] = schema;
+        rememberDefinition(order, unique);
+        rewriteDefName(owner, name, unique);
+        rewriteDefName(schema, name, unique);
+    }
+}
+function rememberDefinition(order, name) {
+    if (!order.includes(name))
+        order.push(name);
+}
+function orderDefinitions(definitions, order) {
+    const source = asRecord(definitions);
+    if (!source)
+        return definitions;
+    const output = {};
+    for (const name of order) {
+        if (Object.hasOwn(source, name))
+            output[name] = source[name];
+    }
+    for (const name of Object.keys(source)) {
+        if (!Object.hasOwn(output, name))
+            output[name] = source[name];
+    }
+    return output;
+}
+function uniqueName(pool, name) {
+    let suffix = 2;
+    while (Object.hasOwn(pool, `${name}_${suffix}`))
+        suffix += 1;
+    return `${name}_${suffix}`;
+}
+function rewriteDefName(schema, from, to) {
+    const record = asRecord(schema);
+    if (!record)
+        return;
+    if (record.$ref === `#/$defs/${from}`)
+        record.$ref = `#/$defs/${to}`;
+    for (const value of Object.values(record))
+        rewriteDefName(value, from, to);
+}
+function liftSiblings(value) {
+    if (Array.isArray(value))
+        return value.map((item) => liftSiblings(item));
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const lifted = {};
+    for (const [key, child] of Object.entries(record))
+        lifted[key] = liftSiblings(child);
+    if (typeof lifted.$ref !== "string")
+        return lifted;
+    const siblings = { ...lifted };
+    delete siblings.$ref;
+    // readOnly/writeOnly stay beside $ref so generators can wrap the reference itself.
+    const flags = {};
+    for (const key of ["readOnly", "writeOnly"]) {
+        if (siblings[key] === true) {
+            flags[key] = true;
+            delete siblings[key];
+        }
+    }
+    if (Object.keys(siblings).length === 0)
+        return { $ref: lifted.$ref, ...flags };
+    return { allOf: [{ $ref: lifted.$ref }, siblings], ...flags };
+}
+function recursiveNames(definitions) {
+    const names = Object.keys(definitions);
+    const dependencies = new Map(names.map((name) => [name, collectDefRefs(definitions[name])]));
+    const recursive = new Set();
+    const state = new Map();
+    const stack = [];
+    const visit = (name) => {
+        const current = state.get(name) ?? 0;
+        if (current === 1) {
+            const start = stack.indexOf(name);
+            const cycle = stack.slice(start);
+            if (cycle.every((item) => isPureRef(definitions[item]))) {
+                throw circularAliasFailure(name);
+            }
+            for (const item of cycle)
+                recursive.add(item);
+            return;
+        }
+        if (current === 2)
+            return;
+        state.set(name, 1);
+        stack.push(name);
+        for (const dependency of dependencies.get(name) ?? []) {
+            if (dependencies.has(dependency))
+                visit(dependency);
+        }
+        stack.pop();
+        state.set(name, 2);
+    };
+    for (const name of names)
+        visit(name);
+    return recursive;
+}
+function collectDefRefs(value, found = new Set(), seen = new Set()) {
+    if (typeof value !== "object" || value === null || seen.has(value))
+        return found;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectDefRefs(item, found, seen);
+        return found;
+    }
+    const ref = value.$ref;
+    if (typeof ref === "string") {
+        const key = referenceKey(ref);
+        if (key)
+            found.add(key);
+    }
+    for (const child of Object.values(value))
+        collectDefRefs(child, found, seen);
+    return found;
+}
+const rootDefRef = (name) => `#/root-defs/${JsonPointer.escapeToken(name)}`;
+function resolveValue(value, definitions, rootDefs, recursive, aliases, resolving, mode, hooks, pointer) {
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            value[index] = resolveValue(value[index], definitions, rootDefs, recursive, aliases, resolving, mode, hooks, joinPointer(pointer, String(index)));
+        }
+        return value;
+    }
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    if (typeof record.$ref === "string") {
+        const key = referenceKey(record.$ref);
+        if (!key)
+            return record;
+        if (!Object.hasOwn(definitions, key)) {
+            if (rootDefs.has(key)) {
+                record.$ref = rootDefRef(key);
+                return record;
+            }
+            throw missingPointerFailure(key, record.$ref, record.$ref);
+        }
+        const final = finalName(key, definitions, aliases);
+        const ref = joinPointer("#/$defs", final);
+        if (recursive.has(final) || mode === "bundle") {
+            if (recursive.has(final))
+                hooks?.onCircular?.(pointer);
+            record.$ref = ref;
+            return record;
+        }
+        if (resolving.has(final))
+            throw circularAliasFailure(final);
+        resolving.add(final);
+        const resolved = resolveValue(structuredClone(definitions[final]), definitions, rootDefs, recursive, aliases, resolving, mode, hooks, ref);
+        resolving.delete(final);
+        hooks?.onDereference?.(pointer, resolved, record, "$ref");
+        return resolved;
+    }
+    for (const [key, child] of Object.entries(record)) {
+        record[key] = resolveValue(child, definitions, rootDefs, recursive, aliases, resolving, mode, hooks, joinPointer(pointer, key));
+    }
+    return record;
+}
+function finalName(name, definitions, aliases) {
+    if (aliases.has(name)) {
+        const cached = aliases.get(name);
+        if (cached == null)
+            throw circularAliasFailure(name);
+        return cached;
+    }
+    aliases.set(name, null);
+    const schema = definitions[name];
+    if (isPureRef(schema)) {
+        const key = referenceKey(schema.$ref);
+        if (key && Object.hasOwn(definitions, key)) {
+            const resolved = finalName(key, definitions, aliases);
+            aliases.set(name, resolved);
+            return resolved;
+        }
+    }
+    aliases.set(name, name);
+    return name;
+}
+function isPureRef(value) {
+    const record = asRecord(value);
+    return Boolean(record && typeof record.$ref === "string" && Object.keys(record).length === 1);
+}
+function referenceKey(ref) {
+    if (!ref.startsWith("#"))
+        return undefined;
+    const tokens = JsonPointer.parseUriFragment(ref);
+    if (tokens === undefined)
+        throw invalidPointerFailure(ref, ref);
+    return tokens.length === 2 && tokens[0] === "$defs" ? tokens[1] : undefined;
+}
+function park(value, scope, id, pointer, saved) {
+    const record = asRecord(value);
+    if (!record)
+        return;
+    for (const key of ANNOTATIONS) {
+        if (!Object.hasOwn(record, key))
+            continue;
+        saved.push({ scope, id, pointer: [...pointer], key, value: record[key] });
+        delete record[key];
+    }
+    for (const key of NESTED_SINGLE)
+        park(record[key], scope, id, [...pointer, key], saved);
+    for (const key of NESTED_ARRAY) {
+        if (!Array.isArray(record[key]))
+            continue;
+        record[key].forEach((item, index) => park(item, scope, id, [...pointer, key, String(index)], saved));
+    }
+    for (const key of NESTED_MAP) {
+        const map = asRecord(record[key]);
+        if (!map)
+            continue;
+        for (const child of Object.keys(map))
+            park(map[child], scope, id, [...pointer, key, child], saved);
+    }
+}
+function restore(converted, saved) {
+    for (const annotation of saved) {
+        const schema = annotation.scope === "definition"
+            ? converted.definitions[annotation.id]
+            : converted.schemas[Number(annotation.id)];
+        const target = annotation.pointer.length === 0 ? schema : descend(schema, annotation.pointer);
+        const record = asRecord(target);
+        if (record)
+            record[annotation.key] = annotation.value;
+    }
+}
+function descend(value, pointer) {
+    let current = value;
+    for (const token of pointer) {
+        if (Array.isArray(current)) {
+            current = current[Number(token)];
+            continue;
+        }
+        const record = asRecord(current);
+        if (!record)
+            return undefined;
+        current = record[token];
+    }
+    return current;
+}
+function restoreRootDefs(document) {
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        const record = asRecord(value);
+        if (!record)
+            return;
+        if (typeof record.$ref === "string" && record.$ref.startsWith("#/root-defs/")) {
+            const name = record.$ref.slice("#/root-defs/".length);
+            record.$ref = joinPointer("#/$defs", JsonPointer.unescapeToken(name));
+        }
+        for (const child of Object.values(record))
+            visit(child);
+    };
+    visit(document);
+}
+function rewriteLeftoverDefinitionRefs(document) {
+    const names = new Set(Object.keys(asRecord(asRecord(document.components)?.schemas) ?? {}));
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        const record = asRecord(value);
+        if (!record)
+            return;
+        if (typeof record.$ref === "string" && record.$ref.startsWith("#/$defs/")) {
+            const tokens = JsonPointer.parseUriFragment(record.$ref);
+            const name = tokens?.[0] === "$defs" ? tokens[1] : undefined;
+            if (name && names.has(name)) {
+                record.$ref = joinPointer("#/components/schemas", [name, ...(tokens?.slice(2) ?? [])]);
+            }
+        }
+        for (const child of Object.values(record))
+            visit(child);
+    };
+    visit(document);
+}
+export function inlineRemaining(document, recursive, hooks) {
+    const visiting = new Set();
+    const walk = (value, parent, key, pointer = "#") => {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index++) {
+                walk(value[index], value, String(index), joinPointer(pointer, String(index)));
+            }
+            return;
+        }
+        const record = asRecord(value);
+        if (!record)
+            return;
+        if (typeof record.$ref === "string" && record.$ref.startsWith("#") && parent && key) {
+            const ref = record.$ref;
+            const name = componentSchemaName(ref);
+            if (name && recursive.has(name)) {
+                hooks?.onCircular?.(pointer);
+                return;
+            }
+            if (visiting.has(ref)) {
+                hooks?.onCircular?.(pointer);
+                return;
+            }
+            const target = getAt(document, ref, ref);
+            visiting.add(ref);
+            const copy = structuredClone(target);
+            walk(copy, undefined, undefined, ref);
+            visiting.delete(ref);
+            parent[key] = copy;
+            hooks?.onDereference?.(pointer, copy, parent, key);
+            return;
+        }
+        for (const [childKey, child] of Object.entries(record)) {
+            walk(child, record, childKey, joinPointer(pointer, childKey));
+        }
+    };
+    walk(document);
+}
+function componentSchemaName(ref) {
+    const tokens = JsonPointer.parseUriFragment(ref);
+    if (!tokens || tokens[0] !== "components" || tokens[1] !== "schemas" || tokens.length !== 3)
+        return undefined;
+    return tokens[2];
+}

package/dist/plugins.d.ts

@@ -0,0 +1,95 @@
+import { Effect, type FileSystem, Schema } from "effect";
+import type { HttpClient } from "effect/http";
+import type { TaggedFailure } from "./errors.ts";
+export interface FileInfo {
+    url: string;
+    extension: string;
+    data?: Uint8Array | string;
+}
+declare const httpResolverOptions: Schema.Struct<{
+    readonly headers: Schema.optional<Schema.Union<readonly [Schema.$Record<Schema.String, Schema.String>, Schema.Null]>>;
+    readonly timeout: Schema.optional<Schema.Finite>;
+    readonly redirects: Schema.optional<Schema.Finite>;
+    readonly withCredentials: Schema.optional<Schema.Boolean>;
+    readonly safeUrlResolver: Schema.optional<Schema.Boolean>;
+    readonly allowedOrigins: Schema.optional<Schema.$Array<Schema.String>>;
+}>;
+export type HttpResolverOptions = typeof httpResolverOptions.Type;
+declare const resolverPluginShape: Schema.Struct<{
+    readonly order: Schema.optional<Schema.Finite>;
+    readonly canRead: Schema.declare<(file: FileInfo) => boolean, (file: FileInfo) => boolean>;
+    readonly read: Schema.declare<(file: FileInfo) => Uint8Array | string | Promise<Uint8Array | string>, (file: FileInfo) => Uint8Array | string | Promise<Uint8Array | string>>;
+}>;
+export type ResolverPlugin = typeof resolverPluginShape.Type;
+declare const parserPluginShape: Schema.Struct<{
+    readonly order: Schema.optional<Schema.Finite>;
+    readonly canParse: Schema.declare<(file: FileInfo) => boolean, (file: FileInfo) => boolean>;
+    readonly parse: Schema.declare<(file: FileInfo) => unknown, (file: FileInfo) => unknown>;
+}>;
+export type ParserPlugin = typeof parserPluginShape.Type;
+declare const bundleHooksShape: Schema.Struct<{
+    readonly onBundle: Schema.optional<Schema.declare<(ref: string, value: unknown, parent: object, key: string) => void, (ref: string, value: unknown, parent: object, key: string) => void>>;
+}>;
+export type BundleHooks = typeof bundleHooksShape.Type;
+declare const dereferenceHooksShape: Schema.Struct<{
+    readonly onDereference: Schema.optional<Schema.declare<(path: string, value: unknown, parent: object, key: string | number) => void, (path: string, value: unknown, parent: object, key: string | number) => void>>;
+    readonly onCircular: Schema.optional<Schema.declare<(path: string) => void, (path: string) => void>>;
+}>;
+export type DereferenceHooks = typeof dereferenceHooksShape.Type;
+export declare const Options: Schema.Struct<{
+    readonly continueOnError: Schema.optional<Schema.Boolean>;
+    readonly keepUrlRefs: Schema.optional<Schema.Boolean>;
+    readonly resolve: Schema.optional<Schema.Struct<{
+        readonly file: Schema.optional<Schema.Boolean>;
+        readonly http: Schema.optional<Schema.Union<readonly [Schema.Boolean, Schema.Struct<{
+            readonly headers: Schema.optional<Schema.Union<readonly [Schema.$Record<Schema.String, Schema.String>, Schema.Null]>>;
+            readonly timeout: Schema.optional<Schema.Finite>;
+            readonly redirects: Schema.optional<Schema.Finite>;
+            readonly withCredentials: Schema.optional<Schema.Boolean>;
+            readonly safeUrlResolver: Schema.optional<Schema.Boolean>;
+            readonly allowedOrigins: Schema.optional<Schema.$Array<Schema.String>>;
+        }>]>>;
+    }>>;
+    readonly parse: Schema.optional<Schema.Struct<{
+        readonly json: Schema.optional<Schema.Boolean>;
+        readonly yaml: Schema.optional<Schema.Boolean>;
+    }>>;
+    readonly resolvers: Schema.optional<Schema.$Array<Schema.declare<{
+        readonly order?: number | undefined;
+        readonly canRead: (file: FileInfo) => boolean;
+        readonly read: (file: FileInfo) => Uint8Array | string | Promise<Uint8Array | string>;
+    }, {
+        readonly order?: number | undefined;
+        readonly canRead: (file: FileInfo) => boolean;
+        readonly read: (file: FileInfo) => Uint8Array | string | Promise<Uint8Array | string>;
+    }>>>;
+    readonly parsers: Schema.optional<Schema.$Array<Schema.declare<{
+        readonly order?: number | undefined;
+        readonly canParse: (file: FileInfo) => boolean;
+        readonly parse: (file: FileInfo) => unknown;
+    }, {
+        readonly order?: number | undefined;
+        readonly canParse: (file: FileInfo) => boolean;
+        readonly parse: (file: FileInfo) => unknown;
+    }>>>;
+    readonly bundle: Schema.optional<Schema.declare<{
+        readonly onBundle?: ((ref: string, value: unknown, parent: object, key: string) => void) | undefined;
+    }, {
+        readonly onBundle?: ((ref: string, value: unknown, parent: object, key: string) => void) | undefined;
+    }>>;
+    readonly dereference: Schema.optional<Schema.declare<{
+        readonly onDereference?: ((path: string, value: unknown, parent: object, key: string | number) => void) | undefined;
+        readonly onCircular?: ((path: string) => void) | undefined;
+    }, {
+        readonly onDereference?: ((path: string, value: unknown, parent: object, key: string | number) => void) | undefined;
+        readonly onCircular?: ((path: string) => void) | undefined;
+    }>>;
+}>;
+export type Options = typeof Options.Type;
+export interface EffectPlugin<A> {
+    order: number;
+    can: (file: FileInfo) => boolean;
+    run: (file: FileInfo) => Effect.Effect<A, TaggedFailure, FileSystem.FileSystem | HttpClient.HttpClient>;
+}
+export declare function promisePlugin<A>(order: number, can: (file: FileInfo) => boolean, run: (file: FileInfo) => A | Promise<A>, onError: (cause: unknown, file: FileInfo) => TaggedFailure): EffectPlugin<A>;
+export {};

package/dist/plugins.js

@@ -0,0 +1,61 @@
+import { Effect, Predicate, Schema } from "effect";
+function callback() {
+    return Schema.declare((value) => Predicate.isFunction(value));
+}
+const httpResolverOptions = Schema.Struct({
+    headers: Schema.optional(Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null])),
+    timeout: Schema.optional(Schema.Finite),
+    redirects: Schema.optional(Schema.Finite),
+    withCredentials: Schema.optional(Schema.Boolean),
+    safeUrlResolver: Schema.optional(Schema.Boolean),
+    allowedOrigins: Schema.optional(Schema.Array(Schema.String)),
+});
+const resolverPluginShape = Schema.Struct({
+    order: Schema.optional(Schema.Finite),
+    canRead: callback(),
+    read: callback(),
+});
+const resolverPlugin = Schema.declare(Schema.is(resolverPluginShape));
+const parserPluginShape = Schema.Struct({
+    order: Schema.optional(Schema.Finite),
+    canParse: callback(),
+    parse: callback(),
+});
+const parserPlugin = Schema.declare(Schema.is(parserPluginShape));
+const bundleHooksShape = Schema.Struct({
+    onBundle: Schema.optional(callback()),
+});
+const bundleHooks = Schema.declare(Schema.is(bundleHooksShape));
+const dereferenceHooksShape = Schema.Struct({
+    onDereference: Schema.optional(callback()),
+    onCircular: Schema.optional(callback()),
+});
+const dereferenceHooks = Schema.declare(Schema.is(dereferenceHooksShape));
+export const Options = Schema.Struct({
+    continueOnError: Schema.optional(Schema.Boolean),
+    keepUrlRefs: Schema.optional(Schema.Boolean),
+    resolve: Schema.optional(Schema.Struct({
+        file: Schema.optional(Schema.Boolean),
+        http: Schema.optional(Schema.Union([Schema.Boolean, httpResolverOptions])),
+    })),
+    parse: Schema.optional(Schema.Struct({
+        json: Schema.optional(Schema.Boolean),
+        yaml: Schema.optional(Schema.Boolean),
+    })),
+    resolvers: Schema.optional(Schema.Array(resolverPlugin)),
+    parsers: Schema.optional(Schema.Array(parserPlugin)),
+    bundle: Schema.optional(bundleHooks),
+    dereference: Schema.optional(dereferenceHooks),
+});
+export function promisePlugin(order, can, run, onError) {
+    return {
+        order,
+        can,
+        run(file) {
+            return Effect.tryPromise({
+                try: () => Promise.resolve(run(file)),
+                catch: (cause) => onError(cause, file),
+            });
+        },
+    };
+}

package/dist/pointer.d.ts

@@ -0,0 +1,7 @@
+export declare function parsePointer(pointer: string, source?: string): string[];
+/** Join pointer tokens without percent-encoding, so `$` stays literal. */
+export declare function joinPointer(base: string, tokens: string | readonly string[]): string;
+export declare function getAt(root: unknown, pointer: string, source?: string): unknown;
+export declare function setAt(root: object, pointer: string, value: unknown): void;
+/** Copy enumerable data, including cycles, and drop non-enumerable parser symbols. */
+export declare function cloneData(value: unknown, seen?: Map<object, unknown>): unknown;

package/dist/pointer.js

@@ -0,0 +1,80 @@
+import { JsonPointer } from "effect";
+import { invalidPointerFailure, missingPointerFailure } from "./errors.js";
+const unsafeTokens = new Set(["__proto__", "constructor", "prototype"]);
+export function parsePointer(pointer, source = pointer) {
+    const hash = pointer.includes("#") ? pointer.slice(pointer.indexOf("#")) : pointer;
+    if (hash === "" || hash === "#")
+        return [];
+    const fragment = hash.startsWith("#") ? hash : `#${hash}`;
+    const tokens = JsonPointer.parseUriFragment(fragment) ?? splitPointer(fragment);
+    if (tokens === undefined)
+        throw invalidPointerFailure(fragment, source);
+    return [...tokens];
+}
+/** Effect's URI-fragment parser rejects spaces. JSON Pointer tokens may contain them. */
+function splitPointer(fragment) {
+    const body = fragment.startsWith("#") ? fragment.slice(1) : fragment;
+    if (body === "")
+        return [];
+    if (!body.startsWith("/"))
+        return undefined;
+    return body
+        .slice(1)
+        .split("/")
+        .map((token) => token.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+/** Join pointer tokens without percent-encoding, so `$` stays literal. */
+export function joinPointer(base, tokens) {
+    const parts = typeof tokens === "string" ? [tokens] : tokens;
+    let pointer = base.includes("#") ? base : `${base}#`;
+    for (const token of parts)
+        pointer += `/${JsonPointer.escapeToken(token)}`;
+    return pointer;
+}
+export function getAt(root, pointer, source = pointer) {
+    const tokens = parsePointer(pointer, source);
+    let current = root;
+    for (const token of tokens) {
+        if (current === null || typeof current !== "object") {
+            throw missingPointerFailure(token, source, pointer);
+        }
+        if (!Object.hasOwn(current, token))
+            throw missingPointerFailure(token, source, pointer);
+        current = current[token];
+    }
+    return current;
+}
+export function setAt(root, pointer, value) {
+    const tokens = parsePointer(pointer, pointer);
+    if (tokens.length === 0 || tokens.some((token) => unsafeTokens.has(token)))
+        return;
+    let current = root;
+    for (let index = 0; index < tokens.length - 1; index++) {
+        const token = tokens[index];
+        const next = current[token];
+        if (next === null || typeof next !== "object" || Array.isArray(next))
+            current[token] = {};
+        current = current[token];
+    }
+    current[tokens[tokens.length - 1]] = value;
+}
+/** Copy enumerable data, including cycles, and drop non-enumerable parser symbols. */
+export function cloneData(value, seen = new Map()) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    const cached = seen.get(value);
+    if (cached !== undefined)
+        return cached;
+    if (Array.isArray(value)) {
+        const copy = [];
+        seen.set(value, copy);
+        for (const item of value)
+            copy.push(cloneData(item, seen));
+        return copy;
+    }
+    const copy = {};
+    seen.set(value, copy);
+    for (const key of Object.keys(value))
+        copy[key] = cloneData(value[key], seen);
+    return copy;
+}