@flowscripter/pluggable-io-framework 1.2.6 → 2.0.0

package/src/util/abort.ts

@@ -0,0 +1,42 @@
+/** The error a transfer rejects with when cancelled through `TransferOptions.signal`. */
+export function createAbortError(): DOMException {
+  return new DOMException("The transfer was aborted", "AbortError");
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw createAbortError();
+  }
+}
+
+/**
+ * Resolves with `"aborted"` or `"stopped"` as soon as `signal` or `stop`
+ * fires, and never otherwise. `dispose` removes the listeners.
+ */
+export function watchSignals(
+  signal: AbortSignal | undefined,
+  stop: AbortSignal | undefined,
+): { readonly fired: Promise<"aborted" | "stopped">; dispose(): void } {
+  const cleanups: (() => void)[] = [];
+  const fired = new Promise<"aborted" | "stopped">((resolve) => {
+    for (const [target, outcome] of [
+      [signal, "aborted"],
+      [stop, "stopped"],
+    ] as const) {
+      if (!target) continue;
+      if (target.aborted) {
+        resolve(outcome);
+        continue;
+      }
+      const listener = () => resolve(outcome);
+      target.addEventListener("abort", listener, { once: true });
+      cleanups.push(() => target.removeEventListener("abort", listener));
+    }
+  });
+  return {
+    fired,
+    dispose() {
+      for (const cleanup of cleanups) cleanup();
+    },
+  };
+}

package/src/util/applyPayloadConverter.ts

@@ -0,0 +1,37 @@
+import {
+  adaptReadableStream,
+  type Item,
+  type PayloadConverter,
+  type PayloadKind,
+} from "@flowscripter/pluggable-io-framework-api";
+
+/**
+ * Converts every item of `stream` for a sink of `toKind`. With a converter,
+ * each item goes through `converter.convert`, including when the kinds match
+ * and only the memory domain differs. Without one, a kind mismatch fails on
+ * the first item.
+ */
+export function applyPayloadConverter(
+  stream: ReadableStream<Item>,
+  fromKind: PayloadKind,
+  toKind: PayloadKind,
+  converter: PayloadConverter | undefined,
+): ReadableStream<Item> {
+  if (!converter) {
+    return adaptReadableStream(stream, fromKind, toKind);
+  }
+  const reader = stream.getReader();
+  return new ReadableStream<Item>({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(converter.convert(value));
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+}

package/src/util/describePath.ts

@@ -0,0 +1,12 @@
+import type { PayloadConverter, PayloadKind } from "@flowscripter/pluggable-io-framework-api";
+
+/** `kind` or `kind[domain]`. */
+export function describeKind(kind: PayloadKind, domain?: string): string {
+  return domain === undefined ? kind : `${kind}[${domain}]`;
+}
+
+/** ` via from->to (zero-copy)` or ` via from->to (copy)`. */
+export function describeConverter(converter: PayloadConverter): string {
+  const cost = converter.cost === 0 ? "zero-copy" : "copy";
+  return ` via ${describeKind(converter.from.kind, converter.from.domain)}->${describeKind(converter.to.kind, converter.to.domain)} (${cost})`;
+}

package/src/util/globToRegex.ts

@@ -0,0 +1,32 @@
+/**
+ * Translates a glob into an anchored regular expression matched against a
+ * single entry name: `*` matches any run of characters except `/`, `?`
+ * matches one such character, and `[...]` is a character class (`[!...]`
+ * negates it). Everything else matches literally.
+ */
+export function globToRegex(glob: string): RegExp {
+  let source = "";
+  for (let i = 0; i < glob.length; i += 1) {
+    const char = glob[i] as string;
+    if (char === "*") {
+      source += "[^/]*";
+    } else if (char === "?") {
+      source += "[^/]";
+    } else if (char === "[") {
+      const close = glob.indexOf("]", i + 2);
+      if (close === -1) {
+        source += "\\[";
+        continue;
+      }
+      let body = glob.slice(i + 1, close);
+      if (body.startsWith("!")) {
+        body = `^${body.slice(1)}`;
+      }
+      source += `[${body.replace(/\\/g, "\\\\")}]`;
+      i = close;
+    } else {
+      source += char.replace(/[.+^${}()|\\/\]]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${source}$`);
+}

package/src/util/itemLength.ts

@@ -0,0 +1,6 @@
+import { type Item, PayloadKind } from "@flowscripter/pluggable-io-framework-api";
+
+/** The payload size of an item in bytes. */
+export function itemLength(item: Item): number {
+  return item.payload.kind === PayloadKind.Js ? item.payload.data.byteLength : item.payload.length;
+}

package/src/util/keys.ts

@@ -0,0 +1,21 @@
+import type { IOProvider } from "@flowscripter/pluggable-io-framework-api";
+
+/** Joins with `/` - the default when a provider has no `joinKey`. */
+export function defaultJoinKey(containerKey: string, name: string): string {
+  if (name === "") return containerKey;
+  if (containerKey === "") return name;
+  return `${containerKey.replace(/\/+$/, "")}/${name}`;
+}
+
+/** Joins a child name onto a container key using the provider's own rule. */
+export function joinKey(provider: IOProvider, containerKey: string, name: string): string {
+  return provider.joinKey
+    ? provider.joinKey(containerKey, name)
+    : defaultJoinKey(containerKey, name);
+}
+
+/** The last segment of a key, treating both `/` and `\` as separators. */
+export function baseName(key: string): string {
+  const segments = key.split(/[\\/]+/).filter((segment) => segment !== "");
+  return segments.at(-1) ?? key;
+}

package/src/util/withParentOperationId.ts

@@ -0,0 +1,17 @@
+import type { TelemetryHooks } from "@flowscripter/pluggable-io-framework-api";
+
+/** Wraps `hooks` so any `onProgress` event passing through gets `parentOperationId` filled in, unless the emitter already set one (nested hierarchy). */
+export function withParentOperationId(
+  hooks: TelemetryHooks | undefined,
+  parentOperationId: string | undefined,
+): TelemetryHooks {
+  if (!hooks || parentOperationId === undefined) {
+    return hooks ?? {};
+  }
+  return {
+    ...hooks,
+    onProgress: hooks.onProgress
+      ? (event) => hooks.onProgress?.({ parentOperationId, ...event })
+      : undefined,
+  };
+}

package/dist/src/ConcurrencyLimiter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ConcurrencyLimiter.d.ts","sourceRoot":"","sources":["../../src/ConcurrencyLimiter.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,kBAAkB;;IAK7B,YAAmB,cAAc,EAAE,MAAM,EAGxC;IAED,IAAW,cAAc,IAAI,MAAM,CAElC;IAEM,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAIrD;IAEY,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQpD;CA0BF;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,oBAAkD,CAAC;AAuDzF;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,CAAC,EAC/C,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAAC,CAAC,CAAC,CAqClB"}

package/dist/src/ConcurrencyLimiter.js

@@ -1,161 +0,0 @@
-const DEFAULT_MAX_CONCURRENCY = 4;
-/**
- * A semaphore bounding how many `run()` callbacks execute at once. A single
- * shared instance (see {@link defaultConcurrencyLimiter}) enforces its cap
- * *globally* across concurrently invoked `copy()`/`move()` calls, not just
- * within one call - two folder copies started at the same time and sharing
- * a limiter will never together exceed its `maxConcurrency`.
- */
-export class ConcurrencyLimiter {
-    #maxConcurrency;
-    #active = 0;
-    #queue = [];
-    constructor(maxConcurrency) {
-        ConcurrencyLimiter.#validate(maxConcurrency);
-        this.#maxConcurrency = maxConcurrency;
-    }
-    get maxConcurrency() {
-        return this.#maxConcurrency;
-    }
-    setMaxConcurrency(maxConcurrency) {
-        ConcurrencyLimiter.#validate(maxConcurrency);
-        this.#maxConcurrency = maxConcurrency;
-        this.#drain();
-    }
-    async run(fn) {
-        await this.#acquire();
-        try {
-            return await fn();
-        }
-        finally {
-            this.#active -= 1;
-            this.#drain();
-        }
-    }
-    #acquire() {
-        if (this.#active < this.#maxConcurrency) {
-            this.#active += 1;
-            return Promise.resolve();
-        }
-        return new Promise((resolve) => {
-            this.#queue.push(() => {
-                this.#active += 1;
-                resolve();
-            });
-        });
-    }
-    #drain() {
-        while (this.#active < this.#maxConcurrency && this.#queue.length > 0) {
-            this.#queue.shift()?.();
-        }
-    }
-    static #validate(maxConcurrency) {
-        if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) {
-            throw new Error(`maxConcurrency must be a positive integer, got ${maxConcurrency}`);
-        }
-    }
-}
-/**
- * Process-wide default limiter, used by `copy()`/`move()` whenever
- * `TransferOptions.concurrencyLimiter` is omitted - so any two calls in the
- * same process share one cap unless a caller explicitly opts out with its
- * own instance (e.g. for test isolation).
- */
-export const defaultConcurrencyLimiter = new ConcurrencyLimiter(DEFAULT_MAX_CONCURRENCY);
-/** Minimal single-consumer async FIFO queue backing {@link mapAsyncIterableConcurrently}. */
-class AsyncChannel {
-    #items = [];
-    #waiters = [];
-    #closed = false;
-    #hasError = false;
-    #error;
-    push(item) {
-        const waiter = this.#waiters.shift();
-        if (waiter) {
-            waiter.resolve({ value: item, done: false });
-        }
-        else {
-            this.#items.push(item);
-        }
-    }
-    close() {
-        this.#closed = true;
-        for (const waiter of this.#waiters.splice(0)) {
-            if (this.#hasError) {
-                waiter.reject(this.#error);
-            }
-            else {
-                waiter.resolve({ value: undefined, done: true });
-            }
-        }
-    }
-    fail(error) {
-        this.#hasError = true;
-        this.#error = error;
-        this.close();
-    }
-    async #next() {
-        if (this.#items.length > 0) {
-            return { value: this.#items.shift(), done: false };
-        }
-        if (this.#closed) {
-            if (this.#hasError) {
-                throw this.#error;
-            }
-            return { value: undefined, done: true };
-        }
-        return new Promise((resolve, reject) => this.#waiters.push({ resolve, reject }));
-    }
-    [Symbol.asyncIterator]() {
-        return { next: () => this.#next() };
-    }
-}
-/**
- * Pulls items from `source` and runs `fn` on each, bounded by `limiter`:
- * exactly `limiter.maxConcurrency` worker loops each pull-then-process one
- * item at a time through `limiter.run`, so at most that many items are ever
- * pulled/in-flight at once (important for sources like a multipart reader
- * where pulling an item eagerly opens a file/network handle). Results are
- * yielded in completion order, not source order. If `fn` throws, no new
- * items are pulled but already-in-flight ones are allowed to finish before
- * the error is rethrown from the returned iterable.
- */
-export function mapAsyncIterableConcurrently(source, fn, limiter) {
-    const channel = new AsyncChannel();
-    const iterator = source[Symbol.asyncIterator]();
-    let stopped = false;
-    let firstError;
-    let errorRecorded = false;
-    async function worker() {
-        for (;;) {
-            if (stopped)
-                return;
-            const { done, value } = await iterator.next();
-            if (done)
-                return;
-            try {
-                const result = await limiter.run(() => fn(value));
-                channel.push(result);
-            }
-            catch (error) {
-                stopped = true;
-                if (!errorRecorded) {
-                    errorRecorded = true;
-                    firstError = error;
-                }
-                return;
-            }
-        }
-    }
-    void (async () => {
-        const workerCount = Math.max(1, limiter.maxConcurrency);
-        await Promise.all(Array.from({ length: workerCount }, () => worker()));
-        if (errorRecorded) {
-            channel.fail(firstError);
-        }
-        else {
-            channel.close();
-        }
-    })();
-    return channel;
-}

package/dist/src/ProviderRegistry.d.ts

@@ -1,14 +0,0 @@
-import type { PluginManager } from "@flowscripter/dynamic-plugin-framework";
-import { type IOProvider } from "@flowscripter/pluggable-io-framework-api";
-/**
- * Wraps a `dynamic-plugin-framework` {@link PluginManager} to discover and
- * instantiate pluggable-io-framework source/sink provider plugins.
- */
-export declare class ProviderRegistry {
-    private readonly pluginManager;
-    constructor(pluginManager: PluginManager);
-    discover(): Promise<void>;
-    listAvailableProviders(): Promise<readonly import("@flowscripter/dynamic-plugin-framework").ExtensionInfo[]>;
-    createProvider(extensionHandle: string, config: unknown): Promise<IOProvider>;
-}
-//# sourceMappingURL=ProviderRegistry.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"ProviderRegistry.d.ts","sourceRoot":"","sources":["../../src/ProviderRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAEL,KAAK,UAAU,EAEhB,MAAM,0CAA0C,CAAC;AAElD;;;GAGG;AACH,qBAAa,gBAAgB;IACR,OAAO,CAAC,QAAQ,CAAC,aAAa;IAAjD,YAAoC,aAAa,EAAE,aAAa,EAAI;IAEvD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAIrC;IAEY,sBAAsB,uFAIlC;IAEY,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAIzF;CACF"}

package/dist/src/ProviderRegistry.js

@@ -1,22 +0,0 @@
-import { PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT, } from "@flowscripter/pluggable-io-framework-api";
-/**
- * Wraps a `dynamic-plugin-framework` {@link PluginManager} to discover and
- * instantiate pluggable-io-framework source/sink provider plugins.
- */
-export class ProviderRegistry {
-    pluginManager;
-    constructor(pluginManager) {
-        this.pluginManager = pluginManager;
-    }
-    async discover() {
-        await this.pluginManager.registerExtensions(PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT);
-    }
-    async listAvailableProviders() {
-        return this.pluginManager.getRegisteredExtensions(PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT);
-    }
-    async createProvider(extensionHandle, config) {
-        const factory = (await this.pluginManager.instantiate(extensionHandle));
-        const validatedConfig = factory.configSchema.parse(config);
-        return factory.createProvider(validatedConfig);
-    }
-}

package/dist/src/chunkLength.d.ts

@@ -1,3 +0,0 @@
-import { type ChunkRef } from "@flowscripter/pluggable-io-framework-api";
-export declare function chunkLength(chunk: ChunkRef): number;
-//# sourceMappingURL=chunkLength.d.ts.map

package/dist/src/chunkLength.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunkLength.d.ts","sourceRoot":"","sources":["../../src/chunkLength.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AAEpF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEnD"}

package/dist/src/chunkLength.js

@@ -1,4 +0,0 @@
-import { ChunkKind } from "@flowscripter/pluggable-io-framework-api";
-export function chunkLength(chunk) {
-    return chunk.kind === ChunkKind.Js ? chunk.data.byteLength : chunk.length;
-}

package/dist/src/copyMove.d.ts

@@ -1,46 +0,0 @@
-import { type ChunkConverter, type IOProvider, type TelemetryHooks } from "@flowscripter/pluggable-io-framework-api";
-import { type ConcurrencyLimiter } from "./ConcurrencyLimiter.ts";
-import { type RetryOptions } from "./withRetry.ts";
-export interface TransferOptions {
-    readonly telemetry?: TelemetryHooks;
-    /** Minimum file size (bytes) before multipart transfer is attempted over plain streaming. */
-    readonly multipartThreshold?: number;
-    /**
-     * Required only when `source.kind !== sink.kind` - pure-TS code can only
-     * convert chunks already of the target kind (see
-     * `identityChunkConverter`); a real js<->native conversion needs an
-     * FFI-capable converter supplied by a runtime-specific package.
-     */
-    readonly chunkConverter?: ChunkConverter;
-    /**
-     * Bounds concurrent multipart parts and recursive-copy/move entries.
-     * Defaults to the shared {@link 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;
-}
-/**
- * Copies `sourcePath` on `source` to `destPath` on `sink`. When `sourcePath`
- * is a folder, recurses: uses a folder-aware `directCopy` when the source
- * declares `supportsRecursiveDirectTransfer`, otherwise lists the folder and
- * transfers each entry (bounded by `options.concurrencyLimiter`), following
- * `cp -r` target semantics (see {@link resolveRecursiveDestRoot}).
- *
- * For a single file: uses `source.directCopy` when
- * `source.canDirectTransfer?.(sink)` reports eligibility. Otherwise falls
- * back to multipart transfer (when both sides support it, size crosses
- * `options.multipartThreshold`, and part-size negotiation succeeds) or plain
- * streaming - retried per `options.retry` on `TransientIOError`.
- */
-export declare function copy(source: IOProvider, sourcePath: string, sink: IOProvider, destPath: string, options?: TransferOptions): Promise<void>;
-/**
- * Moves `sourcePath` on `source` to `destPath` on `sink`. Folder handling
- * mirrors {@link copy}. For a single file, uses `source.directMove` when
- * eligible, otherwise performs a {@link copy} followed by deleting the
- * source item (each retried independently per `options.retry`).
- */
-export declare function move(source: IOProvider, sourcePath: string, sink: IOProvider, destPath: string, options?: TransferOptions): Promise<void>;
-//# sourceMappingURL=copyMove.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"copyMove.d.ts","sourceRoot":"","sources":["../../src/copyMove.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,UAAU,EAIf,KAAK,cAAc,EACpB,MAAM,0CAA0C,CAAC;AAElD,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,6FAA6F;IAC7F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAmXD;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CACxB,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CACxB,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAOf"}