plugin

(no submodules)

Purpose

The plugin module hosts the fallbackUriPlugin factory — the public entry point of the package. The factory validates its options via Zod, binds the supplied StorageUriResolver for recursive dispatch, builds a streaming-extended adapter implementing every StorageLike method, and returns a frozen UriPlugin ready for registration alongside other scheme handlers. The plugin's adapter routes every operation through the walk + ops modules, threading a per-call DepthContext so nested fallback:// URIs remain bounded.

Features

Boundary Zod validation of options + policy.
Frozen UriPlugin with explicit parse / build round-trip.
Full streaming-extended StorageLike adapter: get, set, delete, exists, list, clear, createReadStream, createWriteStream, getMetadata, plus listUri for raw ListUriResult.
Recursion-safe via DepthContext registered through the parsed __fbctx query parameter.
Refuses clear() (heterogeneous-mirror semantics not well-defined).

Usage: Basic Example

import {
    createStorageUriResolver,
} from "@suaveplan/storage-uri";
import { fallbackUriPlugin } from "@suaveplan/storage-uri-plugin-fallback/plugin";

const resolver = createStorageUriResolver([
    httpPlugin,
    drivePlugin,
    fallbackUriPlugin({
        resolver: () => resolver, // late-bound via a proxy in real wiring
    } as never),
]);

Usage: Advanced Example

import { fallbackUriPlugin } from "@suaveplan/storage-uri-plugin-fallback/plugin";

const plugin = fallbackUriPlugin({
    resolver,
    policy: {
        maxParallel: 2,
        writeMode: "all",
        listFailureMode: "partial",
    },
    events: bus,
});
console.log(plugin.scheme); // "fallback"

API Reference

fallbackUriPlugin(options: FallbackPluginOptions): UriPlugin
FallbackAdapter — adapter shape attached to plugin.adapter.
buildFallbackUri / parseFallbackUri re-exports for caller convenience.

Implementation Notes

The plugin holds the resolver by reference, allowing late binding via a proxy when the resolver instance has not yet been constructed. Each operation parses the input URI to discover any embedded context id; when present, it rehydrates the parent DepthContext from the registry, otherwise it creates a fresh root context. The root context is cleaned up in the finally block to keep the registry leak-free.

2.5 KiB Raw Blame History