@flowscripter/pluggable-io-framework 1.2.6 → 2.0.0

package/dist/src/decorators/seekable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seekable.d.ts","sourceRoot":"","sources":["../../../src/decorators/seekable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,aAAa,EACb,QAAQ,EACR,YAAY,EACb,MAAM,0CAA0C,CAAC;AAElD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,SAAS,EAC1C,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GACzC,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CAiC5B"}
+{"version":3,"file":"seekable.d.ts","sourceRoot":"","sources":["../../../src/decorators/seekable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,aAAa,EACb,QAAQ,EACR,YAAY,EACb,MAAM,0CAA0C,CAAC;AAElD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,WAAW,EAC5C,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GACzC,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CAiC5B"}

package/dist/src/decorators/seekable.js

@@ -1,6 +1,6 @@
 /**
- * Wraps a handle that already supports {@link RangeReadable} (arbitrary
- * byte-range reads) with a {@link Seekable} capability: a single logical
+ * Wraps a handle that already supports `RangeReadable` (arbitrary
+ * byte-range reads) with a `Seekable` capability: a single logical
  * stream whose read position can be jumped via `seek(offset)`, rather than
  * requiring the caller to open a fresh stream per range.
  *

package/dist/src/registry/ProviderRegistry.d.ts

@@ -0,0 +1,52 @@
+import type { PluginManager } from "@flowscripter/dynamic-plugin-framework";
+import { type IOProvider, type IOProviderFactory, type LocationTarget, PayloadKind, type PayloadConverter, type ProviderResolver } from "@flowscripter/pluggable-io-framework-api";
+import type { TransferOptions } from "../transfer/TransferOptions.ts";
+/** Nested provider resolutions allowed before resolution fails. */
+export declare const MAX_RESOLUTION_DEPTH = 4;
+export interface ResolvedProvider {
+    readonly provider: IOProvider;
+    readonly target: LocationTarget;
+}
+export interface TransferProviders {
+    readonly source: ResolvedProvider;
+    readonly dest: ResolvedProvider;
+    /**
+     * The negotiated `converter`, `path` and `writePayloadTypes`, to pass to
+     * `copy`/`move` as is or spread together with caller options.
+     */
+    readonly options: TransferOptions;
+}
+/**
+ * Discovers provider factories and payload converters through a
+ * `dynamic-plugin-framework` `PluginManager`, keyed by protocol and
+ * payload kind, and creates providers for location strings. It is also the
+ * `ProviderResolver` handed to every provider it creates.
+ */
+export declare class ProviderRegistry implements ProviderResolver {
+    #private;
+    private readonly pluginManager;
+    constructor(pluginManager: PluginManager);
+    /**
+     * Instantiates every registered factory and converter once. Fails, naming
+     * both factories, if two share a (protocol, kind) pair or if factories for
+     * the same protocol have different top-level location fields.
+     */
+    discover(): Promise<void>;
+    getProtocols(): string[];
+    getKinds(protocol: string): PayloadKind[];
+    /** The factory for `protocol` and `kind`; without `kind`, the `js` one, else the only one. */
+    getFactory(protocol: string, kind?: PayloadKind): IOProviderFactory | undefined;
+    getConverters(): readonly PayloadConverter[];
+    createProviderForLocation(location: string, options?: {
+        kind?: PayloadKind;
+        domain?: string;
+    }): Promise<ResolvedProvider>;
+    /**
+     * Creates providers for both sides of a transfer, negotiating a common
+     * (kind, domain) and payload type, or a converter.
+     */
+    createProvidersForTransfer(source: string, dest: string, options?: {
+        kind?: PayloadKind;
+    }): Promise<TransferProviders>;
+}
+//# sourceMappingURL=ProviderRegistry.d.ts.map

package/dist/src/registry/ProviderRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderRegistry.d.ts","sourceRoot":"","sources":["../../../src/registry/ProviderRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,WAAW,EACX,KAAK,gBAAgB,EAIrB,KAAK,gBAAgB,EACtB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAOD;;;;;GAKG;AACH,qBAAa,gBAAiB,YAAW,gBAAgB;;IAIpC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAAjD,YAAoC,aAAa,EAAE,aAAa,EAAI;IAEpE;;;;OAIG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAqCrC;IAEM,YAAY,IAAI,MAAM,EAAE,CAE9B;IAEM,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAE/C;IAED,8FAA8F;IACvF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAKrF;IAEM,aAAa,IAAI,SAAS,gBAAgB,EAAE,CAElD;IAEM,yBAAyB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,OAAO,CAAC,gBAAgB,CAAC,CAE3B;IAED;;;OAGG;IACU,0BAA0B,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,WAAW,CAAA;KAAE,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAwC5B;CAqEF"}

package/dist/src/registry/ProviderRegistry.js

@@ -0,0 +1,148 @@
+import { BYTES_PAYLOAD_TYPE, PayloadKind, PermanentIOError, PLUGGABLE_IO_FRAMEWORK_PAYLOAD_CONVERTER_EXTENSION_POINT, PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT, } from "@flowscripter/pluggable-io-framework-api";
+import { detectProtocol } from "./detectProtocol.js";
+import { DEFAULT_NATIVE_DOMAINS, negotiateTransfer } from "./negotiateTransfer.js";
+/** Nested provider resolutions allowed before resolution fails. */
+export const MAX_RESOLUTION_DEPTH = 4;
+function locationFieldNames(factory) {
+    const shape = factory.locationSchema.shape;
+    return Object.keys(shape ?? {}).sort();
+}
+/**
+ * Discovers provider factories and payload converters through a
+ * `dynamic-plugin-framework` `PluginManager`, keyed by protocol and
+ * payload kind, and creates providers for location strings. It is also the
+ * `ProviderResolver` handed to every provider it creates.
+ */
+export class ProviderRegistry {
+    pluginManager;
+    #factories = new Map();
+    #converters = [];
+    constructor(pluginManager) {
+        this.pluginManager = pluginManager;
+    }
+    /**
+     * Instantiates every registered factory and converter once. Fails, naming
+     * both factories, if two share a (protocol, kind) pair or if factories for
+     * the same protocol have different top-level location fields.
+     */
+    async discover() {
+        const factories = new Map();
+        const handles = new Map();
+        for (const extension of await this.#extensions(PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT)) {
+            const factory = (await this.pluginManager.instantiate(extension.extensionHandle));
+            handles.set(factory, extension.extensionHandle);
+            const byKind = factories.get(factory.protocol) ?? new Map();
+            const clash = byKind.get(factory.kind);
+            if (clash) {
+                throw new Error(`Factories "${handles.get(clash)}" and "${extension.extensionHandle}" both provide protocol "${factory.protocol}" with payload kind "${factory.kind}"`);
+            }
+            for (const other of byKind.values()) {
+                if (locationFieldNames(other).join() !== locationFieldNames(factory).join()) {
+                    throw new Error(`Factories "${handles.get(other)}" and "${extension.extensionHandle}" for protocol "${factory.protocol}" have different location fields`);
+                }
+            }
+            byKind.set(factory.kind, factory);
+            factories.set(factory.protocol, byKind);
+        }
+        const converters = [];
+        for (const extension of await this.#extensions(PLUGGABLE_IO_FRAMEWORK_PAYLOAD_CONVERTER_EXTENSION_POINT)) {
+            converters.push((await this.pluginManager.instantiate(extension.extensionHandle)));
+        }
+        this.#factories = factories;
+        this.#converters = converters;
+    }
+    getProtocols() {
+        return [...this.#factories.keys()].sort();
+    }
+    getKinds(protocol) {
+        return [...(this.#factories.get(protocol)?.keys() ?? [])].sort();
+    }
+    /** The factory for `protocol` and `kind`; without `kind`, the `js` one, else the only one. */
+    getFactory(protocol, kind) {
+        const byKind = this.#factories.get(protocol);
+        if (!byKind)
+            return undefined;
+        if (kind !== undefined)
+            return byKind.get(kind);
+        return byKind.get(PayloadKind.Js) ?? byKind.values().next().value;
+    }
+    getConverters() {
+        return this.#converters;
+    }
+    createProviderForLocation(location, options) {
+        return this.#resolve(location, options, 0);
+    }
+    /**
+     * Creates providers for both sides of a transfer, negotiating a common
+     * (kind, domain) and payload type, or a converter.
+     */
+    async createProvidersForTransfer(source, dest, options) {
+        const sourceProtocol = detectProtocol(source);
+        const destProtocol = detectProtocol(dest);
+        const sourceFactories = this.#factoriesFor(sourceProtocol, options?.kind);
+        const destFactories = this.#factoriesFor(destProtocol, options?.kind);
+        const negotiation = negotiateTransfer(sourceProtocol, sourceFactories, destProtocol, destFactories, this.#converters, options?.kind);
+        const sourceResolved = await this.#instantiate(negotiation.source.factory, source, negotiation.source.domain, 0);
+        let destResolved;
+        try {
+            destResolved = await this.#instantiate(negotiation.dest.factory, dest, negotiation.dest.domain, 0);
+        }
+        catch (error) {
+            await sourceResolved.provider[Symbol.asyncDispose]();
+            throw error;
+        }
+        return {
+            source: sourceResolved,
+            dest: destResolved,
+            options: {
+                converter: negotiation.converter,
+                path: negotiation.path,
+                writePayloadTypes: negotiation.dest.factory.writePayloadTypes ?? [BYTES_PAYLOAD_TYPE],
+            },
+        };
+    }
+    #extensions(extensionPoint) {
+        return this.pluginManager
+            .registerExtensions(extensionPoint)
+            .then(() => this.pluginManager.getRegisteredExtensions(extensionPoint));
+    }
+    #factoriesFor(protocol, kind) {
+        const byKind = this.#factories.get(protocol);
+        if (!byKind) {
+            throw new Error(`No provider for protocol "${protocol}" (available: ${this.getProtocols().join(", ")})`);
+        }
+        if (kind !== undefined && !byKind.has(kind)) {
+            throw new Error(`No provider for protocol "${protocol}" with payload kind "${kind}" (available: ${this.getKinds(protocol).join(", ")})`);
+        }
+        return [...byKind.values()];
+    }
+    async #resolve(location, options, depth) {
+        if (depth > MAX_RESOLUTION_DEPTH) {
+            throw new PermanentIOError("provider resolution too deep");
+        }
+        const protocol = detectProtocol(location);
+        this.#factoriesFor(protocol, options?.kind);
+        const factory = this.getFactory(protocol, options?.kind);
+        let domain;
+        if (factory.kind === PayloadKind.Native) {
+            const domains = factory.domains ?? DEFAULT_NATIVE_DOMAINS;
+            domain = options?.domain ?? domains[0];
+            if (domain === undefined || !domains.includes(domain)) {
+                throw new Error(`No provider for protocol "${protocol}" supports domain "${domain}" (available: ${domains.join(", ")})`);
+            }
+        }
+        return this.#instantiate(factory, location, domain, depth);
+    }
+    async #instantiate(factory, location, domain, depth) {
+        const parsed = factory.locationSchema.parse(factory.parseLocationString(location));
+        const { config, target } = factory.toProviderInputs(parsed);
+        const resolver = {
+            createProviderForLocation: (inner, opts) => this.#resolve(inner, { kind: opts?.kind ?? factory.kind, domain: opts?.domain ?? domain }, depth + 1),
+        };
+        const provider = await factory.createProvider(factory.configSchema.parse(config), {
+            domain,
+            resolver,
+        });
+        return { provider, target };
+    }
+}

package/dist/src/registry/detectProtocol.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns the protocol of a location string: its URI scheme, lower-cased,
+ * or `"file"` when there is none. A scheme must be at least two characters,
+ * so a Windows drive letter (`C:\foo`) is not read as one. For a composite
+ * scheme the protocol is the part before the first `+`.
+ */
+export declare function detectProtocol(input: string): string;
+//# sourceMappingURL=detectProtocol.d.ts.map

package/dist/src/registry/detectProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectProtocol.d.ts","sourceRoot":"","sources":["../../../src/registry/detectProtocol.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOpD"}

package/dist/src/registry/detectProtocol.js

@@ -0,0 +1,15 @@
+const SCHEME = /^([a-z][a-z0-9+.-]+):/i;
+/**
+ * Returns the protocol of a location string: its URI scheme, lower-cased,
+ * or `"file"` when there is none. A scheme must be at least two characters,
+ * so a Windows drive letter (`C:\foo`) is not read as one. For a composite
+ * scheme the protocol is the part before the first `+`.
+ */
+export function detectProtocol(input) {
+    const match = SCHEME.exec(input);
+    if (!match) {
+        return "file";
+    }
+    const scheme = match[1].toLowerCase();
+    return scheme.split("+")[0];
+}

package/dist/src/registry/negotiateTransfer.d.ts

@@ -0,0 +1,29 @@
+import { type IOProviderFactory, type PayloadConverter, PayloadKind } from "@flowscripter/pluggable-io-framework-api";
+/** One (factory, kind, domain) choice for one side of a transfer. */
+export interface Endpoint {
+    readonly factory: IOProviderFactory;
+    readonly kind: PayloadKind;
+    readonly domain?: string;
+}
+export interface Negotiation {
+    readonly source: Endpoint;
+    readonly dest: Endpoint;
+    readonly converter?: PayloadConverter;
+    readonly path: string;
+}
+export declare const DEFAULT_NATIVE_DOMAINS: readonly string[];
+/** Every (kind, domain) a factory offers, in its preference order. */
+export declare function endpointsOf(factory: IOProviderFactory): Endpoint[];
+/**
+ * Chooses the (kind, domain) for each side of a transfer between factories
+ * of two protocols, considering only pairs that share an exact payload type:
+ * 1. a common (kind, domain), preferring `js`, then the source factory's
+ *    domain order;
+ * 2. otherwise the cheapest single converter from a source pair to a
+ *    destination pair;
+ * 3. otherwise an error listing what each side supports.
+ * An explicit `kind` restricts both sides to it, and allows only converters
+ * that keep it.
+ */
+export declare function negotiateTransfer(sourceProtocol: string, sourceFactories: readonly IOProviderFactory[], destProtocol: string, destFactories: readonly IOProviderFactory[], converters: readonly PayloadConverter[], kind?: PayloadKind): Negotiation;
+//# sourceMappingURL=negotiateTransfer.d.ts.map

package/dist/src/registry/negotiateTransfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiateTransfer.d.ts","sourceRoot":"","sources":["../../../src/registry/negotiateTransfer.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,WAAW,EACZ,MAAM,0CAA0C,CAAC;AAGlD,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAa,CAAC;AAElE,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,EAAE,CASlE;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,SAAS,iBAAiB,EAAE,EAC7C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,IAAI,CAAC,EAAE,WAAW,GACjB,WAAW,CA+Cb"}

package/dist/src/registry/negotiateTransfer.js

@@ -0,0 +1,69 @@
+import { BYTES_PAYLOAD_TYPE, PayloadKind, } from "@flowscripter/pluggable-io-framework-api";
+import { describeConverter, describeKind } from "../util/describePath.js";
+export const DEFAULT_NATIVE_DOMAINS = ["host"];
+/** Every (kind, domain) a factory offers, in its preference order. */
+export function endpointsOf(factory) {
+    if (factory.kind === PayloadKind.Js) {
+        return [{ factory, kind: factory.kind }];
+    }
+    return (factory.domains ?? DEFAULT_NATIVE_DOMAINS).map((domain) => ({
+        factory,
+        kind: factory.kind,
+        domain,
+    }));
+}
+function sharesPayloadType(source, dest) {
+    const reads = source.factory.readPayloadTypes ?? [BYTES_PAYLOAD_TYPE];
+    const writes = dest.factory.writePayloadTypes ?? [BYTES_PAYLOAD_TYPE];
+    return reads.some((payloadType) => writes.includes(payloadType));
+}
+function matches(end, endpoint) {
+    return end.kind === endpoint.kind && (end.domain === undefined || end.domain === endpoint.domain);
+}
+function kindOrder(kind) {
+    return kind === PayloadKind.Js ? 0 : 1;
+}
+function describeSide(protocol, endpoints) {
+    const kinds = endpoints.map((endpoint) => describeKind(endpoint.kind, endpoint.domain));
+    return `"${protocol}" supports [${kinds.join(", ")}]`;
+}
+/**
+ * Chooses the (kind, domain) for each side of a transfer between factories
+ * of two protocols, considering only pairs that share an exact payload type:
+ * 1. a common (kind, domain), preferring `js`, then the source factory's
+ *    domain order;
+ * 2. otherwise the cheapest single converter from a source pair to a
+ *    destination pair;
+ * 3. otherwise an error listing what each side supports.
+ * An explicit `kind` restricts both sides to it, and allows only converters
+ * that keep it.
+ */
+export function negotiateTransfer(sourceProtocol, sourceFactories, destProtocol, destFactories, converters, kind) {
+    const restrict = (factories) => factories
+        .filter((factory) => kind === undefined || factory.kind === kind)
+        .flatMap(endpointsOf)
+        .sort((a, b) => kindOrder(a.kind) - kindOrder(b.kind));
+    const sources = restrict(sourceFactories);
+    const dests = restrict(destFactories);
+    const describe = (source, dest, converter) => `${sourceProtocol}/${describeKind(source.kind, source.domain)} -> ${destProtocol}/${describeKind(dest.kind, dest.domain)}${converter ? describeConverter(converter) : ""}`;
+    const pairs = sources.flatMap((source) => dests.filter((dest) => sharesPayloadType(source, dest)).map((dest) => ({ source, dest })));
+    if (pairs.length === 0 && sources.length > 0 && dests.length > 0) {
+        const reads = sourceFactories.flatMap((f) => f.readPayloadTypes ?? [BYTES_PAYLOAD_TYPE]);
+        const writes = destFactories.flatMap((f) => f.writePayloadTypes ?? [BYTES_PAYLOAD_TYPE]);
+        throw new Error(`No common payload type: "${sourceProtocol}" reads [${[...new Set(reads)].join(", ")}], "${destProtocol}" writes [${[...new Set(writes)].join(", ")}]`);
+    }
+    const common = pairs.find(({ source, dest }) => source.kind === dest.kind && source.domain === dest.domain);
+    if (common) {
+        return { ...common, path: describe(common.source, common.dest) };
+    }
+    const usable = converters
+        .filter((converter) => kind === undefined || (converter.from.kind === kind && converter.to.kind === kind))
+        .toSorted((a, b) => a.cost - b.cost);
+    for (const converter of usable) {
+        const pair = pairs.find(({ source, dest }) => matches(converter.from, source) && matches(converter.to, dest));
+        if (pair) {
+            return { ...pair, converter, path: describe(pair.source, pair.dest, converter) };
+        }
+    }
+    throw new Error(`No common payload kind/domain and no registered converter between ${describeSide(sourceProtocol, sources)} and ${describeSide(destProtocol, dests)}`);
+}

package/dist/src/retry/RetryOptions.d.ts

@@ -0,0 +1,19 @@
+export interface RetryOptions {
+    /**
+     * Maximum retries after a `TransientIOError`. For an unbounded source this
+     * counts consecutive failures and resets once an item arrives.
+     */
+    readonly maxRetries: number;
+    /** Delay in ms before the given retry attempt (1-based). Defaults to `min(200 * 2^attempt, 5000)`. */
+    readonly backoffMs?: (attempt: number) => number;
+    /**
+     * Unbounded sources only: what to do when the source fails and has to be
+     * reconnected, leaving a gap. Defaults to `"continue"`.
+     */
+    readonly onGap?: "continue" | "fail";
+}
+export declare const DEFAULT_RETRY: RetryOptions;
+export declare function defaultBackoffMs(attempt: number): number;
+/** Waits for the backoff delay before retry `attempt`. */
+export declare function backoff(options: RetryOptions, attempt: number): Promise<void>;
+//# sourceMappingURL=RetryOptions.d.ts.map

package/dist/src/retry/RetryOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryOptions.d.ts","sourceRoot":"","sources":["../../../src/retry/RetryOptions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sGAAsG;IACtG,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CACtC;AAED,eAAO,MAAM,aAAa,EAAE,YAAgC,CAAC;AAE7D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG7E"}

package/dist/src/retry/RetryOptions.js

@@ -0,0 +1,9 @@
+export const DEFAULT_RETRY = { maxRetries: 3 };
+export function defaultBackoffMs(attempt) {
+    return Math.min(200 * 2 ** attempt, 5000);
+}
+/** Waits for the backoff delay before retry `attempt`. */
+export function backoff(options, attempt) {
+    const delay = (options.backoffMs ?? defaultBackoffMs)(attempt);
+    return new Promise((resolve) => setTimeout(resolve, delay));
+}

package/dist/src/{withRetry.d.ts → retry/withRetry.d.ts}

@@ -1,8 +1,4 @@
-export interface RetryOptions {
-    readonly maxRetries: number;
-    /** Delay in ms before the given retry attempt (1-based). Defaults to `min(200 * 2^attempt, 5000)`. */
-    readonly backoffMs?: (attempt: number) => number;
-}
+import { type RetryOptions } from "./RetryOptions.ts";
 /**
  * Runs `fn`, retrying only on `TransientIOError` up to `options.maxRetries`
  * times with a delay between attempts. Any other error - including a plain

package/dist/src/retry/withRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withRetry.d.ts","sourceRoot":"","sources":["../../../src/retry/withRetry.ts"],"names":[],"mappings":"AACA,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE/D;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAa1F"}

package/dist/src/{withRetry.js → retry/withRetry.js}

@@ -1,7 +1,5 @@
 import { TransientIOError } from "@flowscripter/pluggable-io-framework-api";
-function defaultBackoffMs(attempt) {
-    return Math.min(200 * 2 ** attempt, 5000);
-}
+import { backoff } from "./RetryOptions.js";
 /**
  * Runs `fn`, retrying only on `TransientIOError` up to `options.maxRetries`
  * times with a delay between attempts. Any other error - including a plain
@@ -9,7 +7,6 @@ function defaultBackoffMs(attempt) {
  * rethrown immediately.
  */
 export async function withRetry(fn, options) {
-    const backoffMs = options.backoffMs ?? defaultBackoffMs;
     let attempt = 0;
     for (;;) {
         try {
@@ -20,7 +17,7 @@ export async function withRetry(fn, options) {
                 throw error;
             }
             attempt += 1;
-            await new Promise((resolve) => setTimeout(resolve, backoffMs(attempt)));
+            await backoff(options, attempt);
         }
     }
 }

package/dist/src/transfer/EntryContext.d.ts

@@ -0,0 +1,16 @@
+import type { TelemetryHooks } from "@flowscripter/pluggable-io-framework-api";
+import type { TransferOptions } from "./TransferOptions.ts";
+/** Per-entry state shared by the transfer strategies. */
+export interface EntryContext {
+    readonly operationId: string;
+    readonly hooks: TelemetryHooks;
+    readonly options: TransferOptions;
+    readonly type: "copy" | "move";
+}
+/** Bytes and items moved by one strategy run, and whether `stop` ended it. */
+export interface EntryOutcome {
+    readonly bytes: number;
+    readonly items: number;
+    readonly stopped: boolean;
+}
+//# sourceMappingURL=EntryContext.d.ts.map

package/dist/src/transfer/EntryContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntryContext.d.ts","sourceRoot":"","sources":["../../../src/transfer/EntryContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B"}

package/dist/src/transfer/EntryContext.js

@@ -0,0 +1 @@
+export {};

package/dist/src/transfer/TransferOptions.d.ts

@@ -0,0 +1,45 @@
+import type { PayloadConverter, TelemetryHooks } from "@flowscripter/pluggable-io-framework-api";
+import type { ConcurrencyLimiter } from "../concurrency/ConcurrencyLimiter.ts";
+import type { RetryOptions } from "../retry/RetryOptions.ts";
+export interface TransferOptions {
+    readonly telemetry?: TelemetryHooks;
+    /** Minimum entry size (bytes) before multipart transfer is attempted over plain streaming. */
+    readonly multipartThreshold?: number;
+    /**
+     * The payload converter chosen by negotiation, applied to every item.
+     * Without one, the source and sink must share a payload kind. Set by the
+     * options `createProvidersForTransfer` returns.
+     */
+    readonly converter?: PayloadConverter;
+    /**
+     * The negotiated path description reported in {@link TransferResult.path}.
+     * Set by the options `createProvidersForTransfer` returns; without it the
+     * path is described from the provider kinds.
+     */
+    readonly path?: string;
+    /**
+     * Payload type IDs the sink's factory accepts, which an opened source
+     * handle's `payloadType` must be one of. Providers don't carry their
+     * factory's declarations, so `createProvidersForTransfer` returns them in
+     * its options. Defaults to `["bytes"]`.
+     */
+    readonly writePayloadTypes?: readonly string[];
+    /**
+     * Bounds concurrent multipart parts and recursive/pattern entries.
+     * Defaults to the shared `defaultConcurrencyLimiter` - so two
+     * `copy()`/`move()` calls in the same process share one cap unless a
+     * caller passes its own isolated instance.
+     */
+    readonly concurrencyLimiter?: ConcurrencyLimiter;
+    /** Retry policy for the non-direct transfer path. Defaults to `{ maxRetries: 3 }`. */
+    readonly retry?: RetryOptions;
+    /** Cancels the transfer: the source is cancelled, the sink aborted, and the transfer rejects with an `AbortError`. */
+    readonly signal?: AbortSignal;
+    /** Ends the transfer gracefully: the source is cancelled, the sink closed normally, and the result reports `stopped`. */
+    readonly stop?: AbortSignal;
+    /** When `false`, `directCopy`/`directMove` are never used. Defaults to `true`. */
+    readonly directTransfer?: boolean;
+    /** Maximum leases outstanding on the lease path, capped by the sink's `maxOutstanding`. Defaults to 2. */
+    readonly leaseDepth?: number;
+}
+//# sourceMappingURL=TransferOptions.d.ts.map

package/dist/src/transfer/TransferOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransferOptions.d.ts","sourceRoot":"","sources":["../../../src/transfer/TransferOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AACjG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,sHAAsH;IACtH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,yHAAyH;IACzH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/dist/src/transfer/TransferOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/src/transfer/TransferResult.d.ts

@@ -0,0 +1,9 @@
+export interface TransferResult {
+    /** Whether `stop` ended the transfer early (output is truncated for a bounded source). */
+    readonly stopped: boolean;
+    readonly bytes: number;
+    readonly items: number;
+    /** Human-readable description of the negotiated transfer path. */
+    readonly path: string;
+}
+//# sourceMappingURL=TransferResult.d.ts.map

package/dist/src/transfer/TransferResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransferResult.d.ts","sourceRoot":"","sources":["../../../src/transfer/TransferResult.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB"}

package/dist/src/transfer/TransferResult.js

@@ -0,0 +1 @@
+export {};

package/dist/src/transfer/aggregateResults.d.ts

@@ -0,0 +1,4 @@
+import type { TransferResult } from "./TransferResult.ts";
+/** Sums per-entry results; the aggregate is stopped if any entry was. */
+export declare function aggregateResults(results: readonly TransferResult[], path: string, stopped: boolean): TransferResult;
+//# sourceMappingURL=aggregateResults.d.ts.map

package/dist/src/transfer/aggregateResults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregateResults.d.ts","sourceRoot":"","sources":["../../../src/transfer/aggregateResults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,yEAAyE;AACzE,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,GACf,cAAc,CAOhB"}

package/dist/src/transfer/aggregateResults.js

@@ -0,0 +1,9 @@
+/** Sums per-entry results; the aggregate is stopped if any entry was. */
+export function aggregateResults(results, path, stopped) {
+    return {
+        stopped: stopped || results.some((result) => result.stopped),
+        bytes: results.reduce((total, result) => total + result.bytes, 0),
+        items: results.reduce((total, result) => total + result.items, 0),
+        path,
+    };
+}

package/dist/src/transfer/copyMove.d.ts

@@ -0,0 +1,23 @@
+import { type IOProvider, type LocationTarget } from "@flowscripter/pluggable-io-framework-api";
+import type { TransferOptions } from "./TransferOptions.ts";
+import type { TransferResult } from "./TransferResult.ts";
+/**
+ * Copies `sourceTarget` on `source` to `destTarget` on `sink`:
+ * - entry -> entry writes exactly the destination key;
+ * - entry -> container writes `<container>/<source basename>`;
+ * - container -> container copies recursively with `cp -r` semantics;
+ * - pattern -> container copies each matching entry;
+ * - container or pattern -> entry, and any pattern destination, are rejected.
+ *
+ * Each entry uses `directCopy` when eligible (and `options.directTransfer`
+ * is not `false`), otherwise multipart, the lease path or plain streaming.
+ */
+export declare function copy(source: IOProvider, sourceTarget: LocationTarget, sink: IOProvider, destTarget: LocationTarget, options?: TransferOptions): Promise<TransferResult>;
+/**
+ * Moves `sourceTarget` on `source` to `destTarget` on `sink`, with the same
+ * target rules as {@link copy}. Non-direct moves copy and then delete the
+ * source. Unbounded sources are rejected, and a stopped move never deletes
+ * its source.
+ */
+export declare function move(source: IOProvider, sourceTarget: LocationTarget, sink: IOProvider, destTarget: LocationTarget, options?: TransferOptions): Promise<TransferResult>;
+//# sourceMappingURL=copyMove.d.ts.map

package/dist/src/transfer/copyMove.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copyMove.d.ts","sourceRoot":"","sources":["../../../src/transfer/copyMove.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EAEpB,MAAM,0CAA0C,CAAC;AAKlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAmE1D;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAClB,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,cAAc,EAC5B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,cAAc,EAC1B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAClB,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,cAAc,EAC5B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,cAAc,EAC1B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAEzB"}