pluggable-io-framework-api

API for the https://github.com/flowscripter/pluggable-io-framework

Key Features

• Defines the IOProviderFactory/IOProvider contract that source/sink plugins (e.g. local filesystem, object storage) implement which are then discovered and loaded via dynamic-plugin-framework.
• IOProvider, StreamHandle and Part are tagged with the single ChunkKind ("js" or "native") a provider natively produces/consumes - streams are homogeneous, so consumers never test each chunk's kind. A mismatch between two linked streams is decided once per link via adaptReadableStream, not once per chunk.
• JsChunk/NativeChunk: a tagged-union stream payload 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.).
• Capabilities beyond plain streaming (e.g. seekable) are modeled as small interfaces (Seekable, RangeReadable) with co-located type guards (isSeekable, isRangeReadable).
• Well-known item properties (size, lastModified, isFolder, contentType) are default for every provider.
• A provider-specific properties extension bag supports other properties (e.g. etag, storage class, custom tags).
• Provider config and per-item property schemas are defined with Zod.
• Multipart transfers are modeled as a stream of independently readable/writable Part handles allowing parts to be processed concurrently.
• A global TelemetryHooks object is supplied once at initialisation and every operation reports through it tagged with a correlation ID.
• Disposal is Symbol.asyncDispose (TC39 explicit resource management) - await using provider = await factory.createProvider(config) disposes deterministically, including on thrown errors.
• See pluggable-io-framework for orchestration and io-plugin-filesystem for a reference 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

classDiagram
    IOProviderFactory --> IOProvider : creates
    IOProvider --> StreamHandle : returns (kind K)
    IOProvider --> Part : returns (multipart, kind K)
    StreamHandle --> JsChunk : streams (kind "js")
    StreamHandle --> NativeChunk : streams (kind "native")
    IOProvider --> ItemProperties : returns

    class IOProviderFactory {
      +configSchema
      +propertySchema
      +createProvider(config)
    }
    class IOProvider {
      +kind: K
      +[Symbol.asyncDispose]()
      +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

License

MIT © Flowscripter