ops/write

Purpose

The ops/write module implements the write-side semantics of the fallback adapter: fallbackSet for byte writes and fallbackWriteStream for streamed writes. Under policy.writeMode: "all" (default) the operation fans out to every candidate via Promise.allSettled so reads from any leg subsequently observe the same content; under "first-success" it walks sequentially and returns on the first leg to succeed, letting remaining writes settle in the background.

Features

Mirror fan-out with structured WRITE_MIRROR_FAILED on any leg failure.
first-success mode with background remainder + best-effort partial emission on the event bus.
AbortSignal short-circuit before dispatch under stopOnAbort.
Stream-input variant buffers chunks then routes through fallbackSet.
Foreign throwables wrapped per leg in MirrorOutcome.error.

Usage: Basic Example

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

await fallbackSet(
    uri,
    new Uint8Array([1, 2, 3]),
    ctx,
    { resolver, policy, events },
    signal,
);

Usage: Advanced Example

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

await fallbackWriteStream(
    uri,
    body,
    ctx,
    {
        resolver,
        policy: { ...policy, writeMode: "first-success" },
        events,
    },
    signal,
);

API Reference

fallbackSet(uri, bytes, ctx, deps, signal): Promise<void>
fallbackWriteStream(uri, body, ctx, deps, signal): Promise<void>
WriteDeps — { resolver, policy, events }.

Implementation Notes

Mirror writes preserve every leg's structured error inside mirrorOutcomes[i].error — foreign throwables are wrapped in FALLBACK_URI.WRITE_MIRROR_FAILED so consumers always receive a SuaveplanError. first-success mode emits a single write-mirror-partial event when at least one background remainder write fails so operators can detect mirror drift.

This module is part of the universal fallback URI plugin family. It coordinates with the recursion, walk, ops, observability, and classification modules through small, narrowly-typed value contracts. The implementation deliberately keeps surface area small so each piece can be substituted or instrumented independently without touching consumers. Refer to the package README for the end-to-end picture and to the spec delta for the requirement matrix this module helps satisfy.

2.4 KiB Raw Permalink Blame History