ops/delete

Purpose

The ops/delete module implements fallbackDelete, the mirror-aware removal operation. It dispatches remove to every candidate via Promise.allSettled. Under the default deleteMode: "any-success" it returns true when at least one candidate confirmed removal; under "all" it throws WRITE_MIRROR_FAILED if any candidate rejects. The result matches StorageLike.delete's boolean contract while preserving structured failure metadata.

Features

Mirror fan-out via Promise.allSettled.
deleteMode: "any-success" (default) and "all" matrix.
Pre-aborted signal short-circuit under stopOnAbort.
Foreign throwables wrapped in MirrorOutcome.error per leg.
Surfaces total failure with WRITE_MIRROR_FAILED when every leg fails.

Usage: Basic Example

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

const removed = await fallbackDelete(
    uri,
    { resolver, policy, events },
    signal,
);

Usage: Advanced Example

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

try {
    await fallbackDelete(
        uri,
        {
            resolver,
            policy: { ...policy, deleteMode: "all" },
            events,
        },
        signal,
    );
} catch (e) {
    if ((e as { code?: string }).code === "FALLBACK_URI.WRITE_MIRROR_FAILED") {
        console.error("delete left a stale mirror behind");
    }
}

API Reference

fallbackDelete(uri, deps, signal): Promise<boolean>
DeleteDeps — { resolver, policy, events }.

Implementation Notes

any-success resolves false when every candidate cleanly reported the key was absent (no failures, no removals). It only throws when every leg actively rejects. deleteMode: "all" upgrades any leg failure to a structured throw so callers needing strict mirror parity can pattern match on the code.

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.3 KiB Raw Blame History