@flowscripter/pluggable-io-framework-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flowscripter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# pluggable-io-framework-api
+
+[![version](https://img.shields.io/github/v/release/flowscripter/pluggable-io-framework-api?sort=semver)](https://github.com/flowscripter/pluggable-io-framework-api/releases)
+[![build](https://img.shields.io/github/actions/workflow/status/flowscripter/pluggable-io-framework-api/release-bun-library.yml)](https://github.com/flowscripter/pluggable-io-framework-api/actions/workflows/release-bun-library.yml)
+[![docs](https://img.shields.io/badge/docs-API-blue)](https://flowscripter.github.io/pluggable-io-framework-api/index.html)
+[![license: MIT](https://img.shields.io/github/license/flowscripter/pluggable-io-framework-api)](https://github.com/flowscripter/pluggable-io-framework-api/blob/main/LICENSE)
+
+> API contracts for [pluggable-io-framework](https://github.com/flowscripter/pluggable-io-framework)
+> source/sink provider plugins
+
+## Key Features
+
+- Defines the `IOProviderFactory`/`IOProvider` contract that source/sink
+  plugins (e.g. local filesystem, object storage) implement, discovered and
+  loaded via
+  [dynamic-plugin-framework](https://github.com/flowscripter/dynamic-plugin-framework).
+- Config and per-item property schemas are defined with
+  [Zod](https://zod.dev) (source of truth), portable to JSON Schema via
+  `zod-to-json-schema` for hand-edited config files or non-TS validation.
+- `ChunkRef`: a tagged-union stream payload (`js` vs `native`) that carries
+  memory ownership/origin with it, enabling zero-copy handoff to/from
+  Rust-FFI-backed providers and decorators, with a small adapter to the
+  standard Web Streams `ReadableStream<Uint8Array>`/`WritableStream<Uint8Array>`
+  for interop (`fetch`, `pipeTo`, etc.).
+- Well-known item properties (`size`, `lastModified`, `isFolder`,
+  `contentType`) guaranteed by every provider, plus a provider-specific
+  `properties` extension bag for anything else (etag, storage class, custom
+  tags).
+- Multipart transfer modeled as a stream of independently readable/writable
+  `Part` handles, so parts can be processed concurrently.
+- Telemetry as a global `TelemetryHooks` object supplied once at
+  initialisation; every operation reports through it tagged with a
+  correlation id.
+- Pure TypeScript, minimal dependencies, no concrete provider
+  implementations - see
+  [pluggable-io-framework](https://github.com/flowscripter/pluggable-io-framework)
+  for orchestration and
+  [pluggable-io-framework-plugin-filesystem](https://github.com/flowscripter/pluggable-io-framework-plugin-filesystem)
+  for a reference implementation.
+
+## Bun Module Usage
+
+Add the module:
+
+`bun add @flowscripter/pluggable-io-framework-api`
+
+Implement a provider factory:
+
+```typescript
+import { z } from "zod";
+import type { IOProviderFactory } from "@flowscripter/pluggable-io-framework-api";
+
+const configSchema = z.object({ rootPath: z.string() });
+const propertySchema = z.object({ etag: z.string().optional() });
+
+const factory: IOProviderFactory<z.infer<typeof configSchema>> = {
+  configSchema,
+  propertySchema,
+  async createProvider(config) {
+    // return an IOProvider implementation
+  },
+};
+```
+
+## Development
+
+Install dependencies:
+
+`bun install`
+
+Build (produces `dist/` for Node.js and TypeScript consumers; Bun uses raw source directly):
+
+`bun run build`
+
+Test:
+
+`bun test`
+
+Format:
+
+`bunx oxfmt`
+
+Lint:
+
+`bunx oxlint index.ts src/ tests/`
+
+Generate HTML API Documentation:
+
+`bunx typedoc index.ts`
+
+## Documentation
+
+### Overview
+
+```mermaid
+classDiagram
+    IOProviderFactory --> IOProvider : creates
+    IOProvider --> StreamHandle : returns
+    IOProvider --> Part : returns (multipart)
+    StreamHandle --> ChunkRef : streams
+    Part --> ChunkRef : streams
+    IOProvider --> ItemProperties : returns
+
+    class IOProviderFactory {
+      +configSchema
+      +propertySchema
+      +createProvider(config)
+    }
+    class IOProvider {
+      +dispose()
+      +list(path, options)
+      +getProperties(path)
+      +setProperties(path, properties)
+      +delete(path)
+      +getReadableStream(path)
+      +getWritableStream(path)
+      +getMultipartReader(path)
+      +getMultipartWriter(path)
+      +canDirectTransfer(other)
+      +directCopy(sourcePath, destPath)
+      +directMove(sourcePath, destPath)
+    }
+```
+
+### API
+
+Link to auto-generated API docs:
+
+[API Documentation](https://flowscripter.github.io/pluggable-io-framework-api/index.html)
+
+## License
+
+MIT © Flowscripter

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./src/ChunkRef.ts";
+export * from "./src/IOProvider.ts";
+export * from "./src/IOProviderFactory.ts";
+export * from "./src/ItemProperties.ts";
+export * from "./src/Part.ts";
+export * from "./src/StreamDecorator.ts";
+export * from "./src/StreamHandle.ts";
+export * from "./src/TelemetryHooks.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./src/ChunkRef.js";
+export * from "./src/IOProvider.js";
+export * from "./src/IOProviderFactory.js";
+export * from "./src/ItemProperties.js";
+export * from "./src/Part.js";
+export * from "./src/StreamDecorator.js";
+export * from "./src/StreamHandle.js";
+export * from "./src/TelemetryHooks.js";

package/dist/src/ChunkRef.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A chunk of stream payload, tagged with its memory origin/ownership.
+ *
+ * This is the actual unit flowing through {@link StreamHandle} and
+ * {@link Part} streams - not a TS-vs-Rust-specific type. A pure-TS pipeline
+ * is simply a stream of `kind: "js"` chunks end to end.
+ *
+ * Tagging origin lets a consumer choose a zero-copy pointer handoff when
+ * compatible (js -> rust always; rust -> rust always) or fall back to an
+ * explicit copy when required (rust -> js, since JS code cannot safely
+ * retain a raw pointer past the call that produced it).
+ *
+ * `attributes` is deliberately shaped close to the future Flowscripter
+ * runtime's Item (attributes + payload) so this type is a natural fit if/when
+ * an `adapt` operator wraps these streams later. It is unused today.
+ */
+export type ChunkRef = {
+    readonly kind: "js";
+    readonly data: Uint8Array;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "native";
+    readonly ptr: number;
+    readonly length: number;
+    release(): void;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+};
+/**
+ * Copy a chunk's bytes into a plain Uint8Array, regardless of origin.
+ * The only copy incurred is for `kind: "native"` chunks.
+ */
+export declare function toUint8Array(chunk: ChunkRef): Uint8Array;
+/**
+ * Adapter to the standard Web Streams interop surface (fetch, pipeTo
+ * external consumers). This is the one clearly-marked copy boundary -
+ * internal source/sink/decorator code speaks {@link ChunkRef} directly.
+ */
+export declare function toWebReadableStream(source: ReadableStream<ChunkRef>): ReadableStream<Uint8Array>;
+export declare function fromWebReadableStream(source: ReadableStream<Uint8Array>): ReadableStream<ChunkRef>;
+//# sourceMappingURL=ChunkRef.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ChunkRef.d.ts","sourceRoot":"","sources":["../../src/ChunkRef.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,QAAQ,GAChB;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD,CAAC;AAEN;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CAOxD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAehG;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GACjC,cAAc,CAAC,QAAQ,CAAC,CAe1B"}

package/dist/src/ChunkRef.js

@@ -0,0 +1,47 @@
+/**
+ * Copy a chunk's bytes into a plain Uint8Array, regardless of origin.
+ * The only copy incurred is for `kind: "native"` chunks.
+ */
+export function toUint8Array(chunk) {
+    if (chunk.kind === "js") {
+        return chunk.data;
+    }
+    throw new Error("Copying a native ChunkRef to Uint8Array requires an FFI-capable runtime helper - not implemented in pluggable-io-framework-api");
+}
+/**
+ * Adapter to the standard Web Streams interop surface (fetch, pipeTo
+ * external consumers). This is the one clearly-marked copy boundary -
+ * internal source/sink/decorator code speaks {@link ChunkRef} directly.
+ */
+export function toWebReadableStream(source) {
+    const reader = source.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            const { done, value } = await reader.read();
+            if (done) {
+                controller.close();
+                return;
+            }
+            controller.enqueue(toUint8Array(value));
+        },
+        cancel(reason) {
+            return reader.cancel(reason);
+        },
+    });
+}
+export function fromWebReadableStream(source) {
+    const reader = source.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            const { done, value } = await reader.read();
+            if (done) {
+                controller.close();
+                return;
+            }
+            controller.enqueue({ kind: "js", data: value });
+        },
+        cancel(reason) {
+            return reader.cancel(reason);
+        },
+    });
+}

package/dist/src/IOProvider.d.ts

@@ -0,0 +1,39 @@
+import type { ItemProperties } from "./ItemProperties.ts";
+import type { Part } from "./Part.ts";
+import type { StreamHandle } from "./StreamHandle.ts";
+/**
+ * A configured source/sink instance, as returned by
+ * {@link IOProviderFactory.createProvider}.
+ *
+ * Disposal is the explicit {@link IOProvider.dispose} method - not a reliance
+ * on `Symbol.asyncDispose` - so plugins have an unambiguous, discoverable
+ * contract for releasing connections/handles.
+ */
+export interface IOProvider {
+    dispose(): Promise<void>;
+    list(path: string, options?: {
+        recursive?: boolean;
+        regex?: RegExp;
+    }): AsyncIterable<{
+        path: string;
+        properties: ItemProperties;
+    }>;
+    getProperties(path: string): Promise<ItemProperties>;
+    setProperties(path: string, properties: Partial<Record<string, unknown>>): Promise<void>;
+    delete(path: string): Promise<void>;
+    getReadableStream(path: string): Promise<StreamHandle>;
+    getWritableStream(path: string): Promise<StreamHandle>;
+    getMultipartReader(path: string): AsyncIterable<Part>;
+    getMultipartWriter(path: string): {
+        write(parts: AsyncIterable<Part>): Promise<void>;
+    };
+    /**
+     * Self-reported direct-transfer eligibility - the provider owns what
+     * "same" means for its backend (e.g. same mount for filesystem, same
+     * bucket+region+credentials for object storage).
+     */
+    canDirectTransfer?(other: IOProvider): boolean;
+    directCopy?(sourcePath: string, destPath: string): Promise<void>;
+    directMove?(sourcePath: string, destPath: string): Promise<void>;
+}
+//# sourceMappingURL=IOProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IOProvider.d.ts","sourceRoot":"","sources":["../../src/IOProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAC/D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACrD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACtD,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAEvF;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;IAC/C,UAAU,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,UAAU,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE"}

package/dist/src/IOProvider.js

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

package/dist/src/IOProviderFactory.d.ts

@@ -0,0 +1,23 @@
+import type { ZodType } from "zod";
+import type { IOProvider } from "./IOProvider.ts";
+/**
+ * Extension point constant that a `dynamic-plugin-framework` `Plugin`'s
+ * `ExtensionDescriptor.extensionPoint` must match to be discovered as a
+ * pluggable-io-framework source/sink provider.
+ */
+export declare const PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT = "@flowscripter/pluggable-io-framework/provider-factory";
+/**
+ * Returned (as `unknown`, cast at the extension point boundary) from
+ * `ExtensionFactory.create()` in a `dynamic-plugin-framework`
+ * `ExtensionDescriptor`.
+ *
+ * Config/property schema: Zod is the source of truth; JSON Schema can be
+ * derived via `zod-to-json-schema` for portability (hand-edited config
+ * files, non-TS validation).
+ */
+export interface IOProviderFactory<TConfig = unknown> {
+    readonly configSchema: ZodType<TConfig>;
+    readonly propertySchema: ZodType<Record<string, unknown>>;
+    createProvider(config: TConfig): Promise<IOProvider>;
+}
+//# sourceMappingURL=IOProviderFactory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IOProviderFactory.d.ts","sourceRoot":"","sources":["../../src/IOProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,uDAAuD,0DACX,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO,GAAG,OAAO;IAClD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtD"}

package/dist/src/IOProviderFactory.js

@@ -0,0 +1,6 @@
+/**
+ * Extension point constant that a `dynamic-plugin-framework` `Plugin`'s
+ * `ExtensionDescriptor.extensionPoint` must match to be discovered as a
+ * pluggable-io-framework source/sink provider.
+ */
+export const PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT = "@flowscripter/pluggable-io-framework/provider-factory";

package/dist/src/ItemProperties.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Properties of a file/folder item. `size`, `lastModified`, `isFolder` and
+ * `contentType` are well-known, framework-guaranteed fields every provider
+ * must populate so generic consumers (CLI, copy/move orchestration) can rely
+ * on them without knowing the provider. Anything provider-specific (etag,
+ * storage class, custom tags) goes in `properties`, validated against that
+ * provider's `propertySchema`.
+ */
+export interface ItemProperties {
+    readonly size: number | undefined;
+    readonly lastModified: Date | undefined;
+    readonly isFolder: boolean;
+    readonly contentType?: string;
+    readonly properties: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=ItemProperties.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ItemProperties.d.ts","sourceRoot":"","sources":["../../src/ItemProperties.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,IAAI,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxD"}

package/dist/src/ItemProperties.js

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

package/dist/src/Part.d.ts

@@ -0,0 +1,13 @@
+import type { ChunkRef } from "./ChunkRef.ts";
+/**
+ * One independently readable/writable part of a multipart transfer.
+ * Parts may be processed concurrently (e.g. `Promise.all` over N parts);
+ * the provider assembles/commits them once all parts finish.
+ */
+export interface Part {
+    readonly index: number;
+    readonly offset: number;
+    readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
+    complete(): Promise<void>;
+}
+//# sourceMappingURL=Part.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Part.d.ts","sourceRoot":"","sources":["../../src/Part.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACrE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/src/Part.js

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

package/dist/src/StreamDecorator.d.ts

@@ -0,0 +1,9 @@
+import type { StreamHandle } from "./StreamHandle.ts";
+/**
+ * A decorator wraps a {@link StreamHandle} and returns an enhanced handle
+ * with additional capability methods (e.g. `seekable` adds `seek`/
+ * `readRange`; `locally-cached` transparently serves repeated reads from a
+ * local cache).
+ */
+export type StreamDecorator = (handle: StreamHandle) => StreamHandle;
+//# sourceMappingURL=StreamDecorator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StreamDecorator.d.ts","sourceRoot":"","sources":["../../src/StreamDecorator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,YAAY,CAAC"}

package/dist/src/StreamDecorator.js

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

package/dist/src/StreamHandle.d.ts

@@ -0,0 +1,15 @@
+import type { ChunkRef } from "./ChunkRef.ts";
+/**
+ * A handle to a readable or writable stream of {@link ChunkRef}s, plus
+ * optional capability methods for providers/decorators that support
+ * random-access beyond plain sequential read (e.g. `seekable`).
+ *
+ * Capability methods are present only when supported - consumers
+ * feature-detect via `typeof handle.seek === "function"` etc.
+ */
+export interface StreamHandle {
+    readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
+    seek?(offset: number): Promise<void>;
+    readRange?(start: number, end: number): Promise<ReadableStream<ChunkRef>>;
+}
+//# sourceMappingURL=StreamHandle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StreamHandle.d.ts","sourceRoot":"","sources":["../../src/StreamHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACrE,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC3E"}

package/dist/src/StreamHandle.js

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

package/dist/src/TelemetryHooks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Global telemetry hooks supplied once at framework initialisation. Every
+ * operation is given a correlation id and reports through the same hooks,
+ * tagged with that id/operation-type - callers don't need to thread a
+ * callback through every call, but can still track individual operations
+ * via the id in emitted events.
+ */
+export interface TelemetryHooks {
+    onProgress?(event: {
+        operationId: string;
+        type: string;
+        bytesProcessed: number;
+        totalBytes?: number;
+    }): void;
+    onMetric?(event: {
+        name: string;
+        value: number;
+        tags?: Record<string, string>;
+    }): void;
+}
+//# sourceMappingURL=TelemetryHooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryHooks.d.ts","sourceRoot":"","sources":["../../src/TelemetryHooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,CAAC,KAAK,EAAE;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,IAAI,CAAC;IACT,QAAQ,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CACxF"}

package/dist/src/TelemetryHooks.js

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

package/index.ts

@@ -0,0 +1,8 @@
+export * from "./src/ChunkRef.ts";
+export * from "./src/IOProvider.ts";
+export * from "./src/IOProviderFactory.ts";
+export * from "./src/ItemProperties.ts";
+export * from "./src/Part.ts";
+export * from "./src/StreamDecorator.ts";
+export * from "./src/StreamHandle.ts";
+export * from "./src/TelemetryHooks.ts";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@flowscripter/pluggable-io-framework-api",
+  "version": "0.1.0",
+  "description": "API contracts for pluggable-io-framework source/sink provider plugins",
+  "keywords": [
+    "api",
+    "bun",
+    "io",
+    "plugin"
+  ],
+  "homepage": "https://github.com/flowscripter/pluggable-io-framework-api#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowscripter/pluggable-io-framework-api.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "oxfmt": "0.57.0",
+    "oxlint": "1.72.0"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "typedocOptions": {
+    "readme": "none",
+    "exclude": [
+      "tests/**"
+    ]
+  }
+}

package/src/ChunkRef.ts

@@ -0,0 +1,83 @@
+/**
+ * A chunk of stream payload, tagged with its memory origin/ownership.
+ *
+ * This is the actual unit flowing through {@link StreamHandle} and
+ * {@link Part} streams - not a TS-vs-Rust-specific type. A pure-TS pipeline
+ * is simply a stream of `kind: "js"` chunks end to end.
+ *
+ * Tagging origin lets a consumer choose a zero-copy pointer handoff when
+ * compatible (js -> rust always; rust -> rust always) or fall back to an
+ * explicit copy when required (rust -> js, since JS code cannot safely
+ * retain a raw pointer past the call that produced it).
+ *
+ * `attributes` is deliberately shaped close to the future Flowscripter
+ * runtime's Item (attributes + payload) so this type is a natural fit if/when
+ * an `adapt` operator wraps these streams later. It is unused today.
+ */
+export type ChunkRef =
+  | {
+      readonly kind: "js";
+      readonly data: Uint8Array;
+      readonly attributes?: Readonly<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: "native";
+      readonly ptr: number;
+      readonly length: number;
+      release(): void;
+      readonly attributes?: Readonly<Record<string, unknown>>;
+    };
+
+/**
+ * Copy a chunk's bytes into a plain Uint8Array, regardless of origin.
+ * The only copy incurred is for `kind: "native"` chunks.
+ */
+export function toUint8Array(chunk: ChunkRef): Uint8Array {
+  if (chunk.kind === "js") {
+    return chunk.data;
+  }
+  throw new Error(
+    "Copying a native ChunkRef to Uint8Array requires an FFI-capable runtime helper - not implemented in pluggable-io-framework-api",
+  );
+}
+
+/**
+ * Adapter to the standard Web Streams interop surface (fetch, pipeTo
+ * external consumers). This is the one clearly-marked copy boundary -
+ * internal source/sink/decorator code speaks {@link ChunkRef} directly.
+ */
+export function toWebReadableStream(source: ReadableStream<ChunkRef>): ReadableStream<Uint8Array> {
+  const reader = source.getReader();
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(toUint8Array(value));
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+}
+
+export function fromWebReadableStream(
+  source: ReadableStream<Uint8Array>,
+): ReadableStream<ChunkRef> {
+  const reader = source.getReader();
+  return new ReadableStream<ChunkRef>({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue({ kind: "js", data: value });
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+}

package/src/IOProvider.ts

@@ -0,0 +1,37 @@
+import type { ItemProperties } from "./ItemProperties.ts";
+import type { Part } from "./Part.ts";
+import type { StreamHandle } from "./StreamHandle.ts";
+
+/**
+ * A configured source/sink instance, as returned by
+ * {@link IOProviderFactory.createProvider}.
+ *
+ * Disposal is the explicit {@link IOProvider.dispose} method - not a reliance
+ * on `Symbol.asyncDispose` - so plugins have an unambiguous, discoverable
+ * contract for releasing connections/handles.
+ */
+export interface IOProvider {
+  dispose(): Promise<void>;
+
+  list(
+    path: string,
+    options?: { recursive?: boolean; regex?: RegExp },
+  ): AsyncIterable<{ path: string; properties: ItemProperties }>;
+  getProperties(path: string): Promise<ItemProperties>;
+  setProperties(path: string, properties: Partial<Record<string, unknown>>): Promise<void>;
+  delete(path: string): Promise<void>;
+
+  getReadableStream(path: string): Promise<StreamHandle>;
+  getWritableStream(path: string): Promise<StreamHandle>;
+  getMultipartReader(path: string): AsyncIterable<Part>;
+  getMultipartWriter(path: string): { write(parts: AsyncIterable<Part>): Promise<void> };
+
+  /**
+   * Self-reported direct-transfer eligibility - the provider owns what
+   * "same" means for its backend (e.g. same mount for filesystem, same
+   * bucket+region+credentials for object storage).
+   */
+  canDirectTransfer?(other: IOProvider): boolean;
+  directCopy?(sourcePath: string, destPath: string): Promise<void>;
+  directMove?(sourcePath: string, destPath: string): Promise<void>;
+}

package/src/IOProviderFactory.ts

@@ -0,0 +1,25 @@
+import type { ZodType } from "zod";
+import type { IOProvider } from "./IOProvider.ts";
+
+/**
+ * Extension point constant that a `dynamic-plugin-framework` `Plugin`'s
+ * `ExtensionDescriptor.extensionPoint` must match to be discovered as a
+ * pluggable-io-framework source/sink provider.
+ */
+export const PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT =
+  "@flowscripter/pluggable-io-framework/provider-factory";
+
+/**
+ * Returned (as `unknown`, cast at the extension point boundary) from
+ * `ExtensionFactory.create()` in a `dynamic-plugin-framework`
+ * `ExtensionDescriptor`.
+ *
+ * Config/property schema: Zod is the source of truth; JSON Schema can be
+ * derived via `zod-to-json-schema` for portability (hand-edited config
+ * files, non-TS validation).
+ */
+export interface IOProviderFactory<TConfig = unknown> {
+  readonly configSchema: ZodType<TConfig>;
+  readonly propertySchema: ZodType<Record<string, unknown>>;
+  createProvider(config: TConfig): Promise<IOProvider>;
+}

package/src/ItemProperties.ts

@@ -0,0 +1,15 @@
+/**
+ * Properties of a file/folder item. `size`, `lastModified`, `isFolder` and
+ * `contentType` are well-known, framework-guaranteed fields every provider
+ * must populate so generic consumers (CLI, copy/move orchestration) can rely
+ * on them without knowing the provider. Anything provider-specific (etag,
+ * storage class, custom tags) goes in `properties`, validated against that
+ * provider's `propertySchema`.
+ */
+export interface ItemProperties {
+  readonly size: number | undefined;
+  readonly lastModified: Date | undefined;
+  readonly isFolder: boolean;
+  readonly contentType?: string;
+  readonly properties: Readonly<Record<string, unknown>>;
+}

package/src/Part.ts

@@ -0,0 +1,13 @@
+import type { ChunkRef } from "./ChunkRef.ts";
+
+/**
+ * One independently readable/writable part of a multipart transfer.
+ * Parts may be processed concurrently (e.g. `Promise.all` over N parts);
+ * the provider assembles/commits them once all parts finish.
+ */
+export interface Part {
+  readonly index: number;
+  readonly offset: number;
+  readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
+  complete(): Promise<void>;
+}

package/src/StreamDecorator.ts

@@ -0,0 +1,9 @@
+import type { StreamHandle } from "./StreamHandle.ts";
+
+/**
+ * A decorator wraps a {@link StreamHandle} and returns an enhanced handle
+ * with additional capability methods (e.g. `seekable` adds `seek`/
+ * `readRange`; `locally-cached` transparently serves repeated reads from a
+ * local cache).
+ */
+export type StreamDecorator = (handle: StreamHandle) => StreamHandle;

package/src/StreamHandle.ts

@@ -0,0 +1,15 @@
+import type { ChunkRef } from "./ChunkRef.ts";
+
+/**
+ * A handle to a readable or writable stream of {@link ChunkRef}s, plus
+ * optional capability methods for providers/decorators that support
+ * random-access beyond plain sequential read (e.g. `seekable`).
+ *
+ * Capability methods are present only when supported - consumers
+ * feature-detect via `typeof handle.seek === "function"` etc.
+ */
+export interface StreamHandle {
+  readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
+  seek?(offset: number): Promise<void>;
+  readRange?(start: number, end: number): Promise<ReadableStream<ChunkRef>>;
+}

package/src/TelemetryHooks.ts

@@ -0,0 +1,16 @@
+/**
+ * Global telemetry hooks supplied once at framework initialisation. Every
+ * operation is given a correlation id and reports through the same hooks,
+ * tagged with that id/operation-type - callers don't need to thread a
+ * callback through every call, but can still track individual operations
+ * via the id in emitted events.
+ */
+export interface TelemetryHooks {
+  onProgress?(event: {
+    operationId: string;
+    type: string;
+    bytesProcessed: number;
+    totalBytes?: number;
+  }): void;
+  onMetric?(event: { name: string; value: number; tags?: Record<string, string> }): void;
+}