io-plugin-filesystem

Local filesystem source/sink plugin for pluggable-io-framework, loaded via dynamic-plugin-framework

Key Features

• Implements the IOProviderFactory/IOProvider contract from pluggable-io-framework-api for the local filesystem - both source and sink.
• Factory for the file protocol with the js payload kind. Locations are file: URLs (file:///foo or file:/foo) or bare paths, validated by filesystemLocationSchema (path, plus an optional filename for a single entry or a glob pattern for matching entries). toProviderInputs joins path and filename with the OS path separator into a LocationTarget.
• Config: { rootPath?: string } (validated with Zod) - rootPath is optional, defaulting to "". All paths passed to provider methods are resolved and sandboxed against rootPath - a path that would escape it is rejected. rootPath: "" (or omitted) is an explicit sentinel for "no restriction" (full filesystem access), since POSIX "/" isn't a meaningful "everything" root on Windows (multiple drive letters, no single filesystem root). Locations parsed from strings always use the unrestricted config.
• list (recursive, regex-filterable), getProperties (size/lastModified/isContainer plus a mode extension property), setProperties (lastModified plus a mode property validated by filesystemSettablePropertySchema), delete, createContainer and joinKey.
• Readable handles implement RangeReadable (readRange(start, end) with an exclusive end). Writable handles implement ResumableWritable: resuming appends from the file's current size, reported as startOffset.
• Multipart writes (concurrent byte-range parts written directly to file offsets via a single shared file handle) at a caller-supplied part size - getPartSizeConstraints reports unconstrained bounds with an 8MB default, since the local filesystem imposes no real part-size limits.
• canDirectTransfer/directCopy/directMove: two FilesystemIOProvider instances with the same rootPath copy/move directly (cp/rename, with an EXDEV cross-device fallback to recursive copy+delete) instead of streaming. supportsRecursiveDirectTransfer is true - a directory sourcePath is copied/moved recursively in one directCopy/directMove call, preserving empty subdirectories.
• Bundled (bun build --target bun) as a single-file plugin, loaded by dynamic-plugin-framework via import() - proven end to end in this repo's tests via a real LocalFolderPluginRepository, not just type-checking.
• Discoverable via NpmPluginRepository (the mechanism behind dynamic-cli-framework's plugin add/plugin list commands): the package.json pluggable-io-framework field declares this package's extension points, so once installed into a CLI's local plugin store it is found without the consuming CLI needing a direct npm dependency on it - also proven end to end in this repo's tests, not just type-checking.

String and Structured Locations

A file location can be given in two forms:

• A string: a file: URL (file:///foo or file:/foo, no host) or a bare path. parseLocationString returns only { path }, so a string always addresses the whole path as a container target. Strings are the convenient form for code holding a path or URL, and the form other providers use when they resolve a file location.
• A structured location object, { path, filename?, pattern? }, validated by filesystemLocationSchema directly. It is needed to address a single file (filename, an entry target) or the files matching a glob (pattern, a pattern target), which a string cannot express.

Bundled Bun Module Usage

Loaded as a dynamic-plugin-framework plugin - see that project's docs for how a host application discovers and instantiates plugins. Direct usage of the bundle, where registry is a pluggable-io-framework ProviderRegistry (or any ProviderResolver):

import filesystemPlugin, {
  filesystemIOProviderFactory,
} from "https://unpkg.com/@flowscripter/io-plugin-filesystem/dist/bundle.js";

const provider = await filesystemIOProviderFactory.createProvider(
  { rootPath: "/data" },
  { resolver: registry },
);

Development

Install dependencies:

bun install

Test:

bun test

Bundle for usage as a dynamic-plugin-framework plugin:

bun run build

Format:

bunx oxfmt

Lint:

bunx oxlint index.ts src/ tests/

Generate HTML API Documentation:

bunx typedoc index.ts

Documentation

Overview

Refer to pluggable-io-framework-api and pluggable-io-framework for the contract and orchestration this plugin implements.

API

Link to auto-generated API docs:

API Documentation

License

MIT © Flowscripter