@poe-platform/safe-fs 0.1.0

package/dist/safe-fs/fs/s3/http/xml.js

@@ -0,0 +1,188 @@
+import { S3ServiceError } from "../transport.js";
+export function malformed(message = "invalid S3 XML response") {
+    throw new S3ServiceError("InvalidResponse", 502, message);
+}
+function validCharacter(code) {
+    return code === 9 || code === 10 || code === 13 || (code >= 32 && code <= 0xd7ff)
+        || (code >= 0xe000 && code <= 0xfffd) || (code >= 0x10000 && code <= 0x10ffff);
+}
+function decodeEntities(text) {
+    let result = "";
+    let position = 0;
+    while (position < text.length) {
+        const start = text.indexOf("&", position);
+        if (start < 0)
+            return result + text.slice(position);
+        result += text.slice(position, start);
+        const end = text.indexOf(";", start + 1);
+        if (end < 0 || end - start > 12)
+            malformed("invalid XML entity");
+        const entity = text.slice(start + 1, end);
+        const named = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+        if (Object.hasOwn(named, entity))
+            result += named[entity];
+        else {
+            const hexadecimal = entity.startsWith("#x");
+            const digits = entity.slice(hexadecimal ? 2 : 1);
+            if (!entity.startsWith("#") || !(hexadecimal ? /^[0-9a-fA-F]+$/ : /^[0-9]+$/).test(digits))
+                malformed("unknown XML entity");
+            const code = Number.parseInt(digits, hexadecimal ? 16 : 10);
+            if (!validCharacter(code))
+                malformed("invalid XML code point");
+            result += String.fromCodePoint(code);
+        }
+        position = end + 1;
+    }
+    return result;
+}
+export function parseXml(bytes) {
+    let xml;
+    try {
+        xml = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return malformed("XML is not UTF-8");
+    }
+    for (const character of xml)
+        if (!validCharacter(character.codePointAt(0)))
+            malformed("invalid XML character");
+    xml = xml.replace(/\r\n?/g, "\n");
+    let position = 0;
+    let nodes = 0;
+    let root;
+    const stack = [];
+    const whitespace = () => { while (position < xml.length && /[ \t\r\n]/.test(xml[position]))
+        position++; };
+    const name = () => {
+        const start = position;
+        if (!/[A-Za-z_]/.test(xml[position] ?? ""))
+            malformed("invalid XML name");
+        while (position < xml.length && /[A-Za-z0-9_.:-]/.test(xml[position]))
+            position++;
+        const result = xml.slice(start, position);
+        if (result.length > 256)
+            malformed("XML name too long");
+        return result;
+    };
+    while (position < xml.length) {
+        if (xml[position] !== "<") {
+            const end = xml.indexOf("<", position);
+            const text = xml.slice(position, end < 0 ? xml.length : end);
+            if (text.includes("]]>"))
+                malformed();
+            const current = stack.at(-1);
+            if (current)
+                current.text += decodeEntities(text);
+            else if (text.trim())
+                malformed("text outside XML root");
+            position = end < 0 ? xml.length : end;
+            continue;
+        }
+        if (xml.startsWith("<?xml ", position) && !root && position === 0) {
+            const end = xml.indexOf("?>", position);
+            if (end < 0 || end > 256)
+                malformed();
+            const declaration = xml.slice(position, end);
+            if (!/^<\?xml\s+version\s*=\s*(?:"1\.0"|'1\.0')(?:\s+encoding\s*=\s*(?:"[Uu][Tt][Ff]-8"|'[Uu][Tt][Ff]-8'))?(?:\s+standalone\s*=\s*(?:"(?:yes|no)"|'(?:yes|no)'))?\s*$/.test(declaration))
+                malformed("unsupported XML declaration");
+            position = end + 2;
+            continue;
+        }
+        if (xml.startsWith("<!--", position)) {
+            const end = xml.indexOf("-->", position + 4);
+            const comment = xml.slice(position + 4, end);
+            if (end < 0 || comment.includes("--") || comment.endsWith("-"))
+                malformed();
+            position = end + 3;
+            continue;
+        }
+        if (xml.startsWith("<![CDATA[", position)) {
+            const end = xml.indexOf("]]>", position + 9);
+            const current = stack.at(-1);
+            if (end < 0 || !current)
+                malformed();
+            current.text += xml.slice(position + 9, end);
+            position = end + 3;
+            continue;
+        }
+        position++;
+        const closing = xml[position] === "/";
+        if (closing)
+            position++;
+        const tag = name();
+        if (closing) {
+            whitespace();
+            if (xml[position++] !== ">" || stack.pop()?.name !== tag)
+                malformed("mismatched XML close tag");
+            continue;
+        }
+        const attributes = new Set();
+        while (true) {
+            const previous = position;
+            whitespace();
+            if (xml[position] === ">" || xml[position] === "/")
+                break;
+            if (previous === position || attributes.size >= 32)
+                malformed("invalid XML attributes");
+            const attribute = name();
+            if (attributes.has(attribute))
+                malformed("duplicate XML attribute");
+            attributes.add(attribute);
+            whitespace();
+            if (xml[position++] !== "=")
+                malformed();
+            whitespace();
+            const quote = xml[position++];
+            if (quote !== '"' && quote !== "'")
+                malformed();
+            const end = xml.indexOf(quote, position);
+            if (end < 0 || xml.slice(position, end).includes("<"))
+                malformed();
+            decodeEntities(xml.slice(position, end));
+            position = end + 1;
+        }
+        const selfClosing = xml[position] === "/";
+        if (selfClosing)
+            position++;
+        if (xml[position++] !== ">")
+            malformed();
+        if (++nodes > 32_768 || stack.length >= 32)
+            malformed("XML structure limit exceeded");
+        const node = { name: tag, text: "", children: [] };
+        const parent = stack.at(-1);
+        if (parent)
+            parent.children.push(node);
+        else if (root)
+            malformed("multiple XML roots");
+        else
+            root = node;
+        if (!selfClosing)
+            stack.push(node);
+    }
+    if (!root || stack.length)
+        malformed("incomplete XML");
+    return root;
+}
+export function children(node, name) {
+    return node.children.filter(child => child.name === name);
+}
+export function text(node, name, required = false) {
+    const matches = children(node, name);
+    if (matches.length > 1 || (required && matches.length !== 1))
+        malformed(`invalid ${name} count`);
+    const child = matches[0];
+    if (child?.children.length)
+        malformed(`invalid ${name} value`);
+    return child?.text;
+}
+export function integer(value) {
+    if (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(Number(value)))
+        malformed("invalid integer");
+    return Number(value);
+}
+export function timestamp(value) {
+    const date = new Date(value);
+    if (!Number.isFinite(date.getTime()))
+        malformed("invalid timestamp");
+    return date;
+}

package/dist/safe-fs/fs/s3/index.d.ts

@@ -0,0 +1,6 @@
+export { S3FileSystem, S3RenameError } from "./filesystem.js";
+export type { S3FileSystemOptions } from "./filesystem.js";
+export { MockS3Client } from "./mock.js";
+export type { MockS3ClientOptions, MockS3Operation, MockS3Request } from "./mock.js";
+export { createS3Transport, encodeCopySource, S3ServiceError } from "./transport.js";
+export type { S3Body, S3Client, S3CopyInput, S3CopyOutput, S3DeleteInput, S3GetOutput, S3HeadOutput, S3ListInput, S3ListOutput, S3ObjectInput, S3ObjectSummary, S3PutInput, S3RequestOptions, S3Transport, S3TransportCapabilities, } from "./transport.js";

package/dist/safe-fs/fs/s3/index.js

@@ -0,0 +1,3 @@
+export { S3FileSystem, S3RenameError } from "./filesystem.js";
+export { MockS3Client } from "./mock.js";
+export { createS3Transport, encodeCopySource, S3ServiceError } from "./transport.js";

package/dist/safe-fs/fs/s3/mock.d.ts

@@ -0,0 +1,48 @@
+import type { S3StreamGetInput, S3StreamGetOutput, S3StreamPutInput } from "./transport.js";
+import type { S3CopyInput, S3CopyOutput, S3DeleteInput, S3GetOutput, S3HeadOutput, S3ListInput, S3ListOutput, S3ObjectInput, S3PutInput, S3RequestOptions, S3Transport } from "./transport.js";
+export type MockS3Operation = "headObject" | "getObject" | "putObject" | "deleteObject" | "copyObject" | "listObjectsV2";
+export interface MockS3Request {
+    readonly operation: MockS3Operation;
+    readonly input: S3ObjectInput | S3ListInput | S3CopyInput | S3PutInput | S3DeleteInput;
+}
+export interface MockS3ClientOptions {
+    readonly buckets: readonly string[];
+    readonly pageSize?: number;
+    readonly now?: () => Date;
+    readonly authorize?: (request: MockS3Request) => void | Promise<void>;
+}
+export declare class MockS3Client implements S3Transport {
+    readonly capabilities: Readonly<{
+        conditionalPut: true;
+        conditionalCopy: true;
+        conditionalDelete: true;
+        streamingRead: true;
+        streamingWrite: true;
+    }>;
+    private readonly buckets;
+    private readonly cursors;
+    private readonly history;
+    private readonly pageSize;
+    private readonly now;
+    private readonly authorize;
+    private nextToken;
+    constructor(options: MockS3ClientOptions);
+    get requests(): readonly MockS3Request[];
+    private begin;
+    private bucket;
+    private object;
+    private head;
+    private store;
+    headObject(input: S3ObjectInput, options?: S3RequestOptions): Promise<S3HeadOutput>;
+    getObject(input: S3ObjectInput, options?: S3RequestOptions): Promise<S3GetOutput>;
+    putObject(input: S3PutInput, options?: S3RequestOptions): Promise<{
+        ETag: string;
+    }>;
+    getObjectStream(input: S3StreamGetInput, options?: S3RequestOptions): Promise<S3StreamGetOutput>;
+    putObjectStream(input: S3StreamPutInput, options?: S3RequestOptions): Promise<{
+        ETag: string;
+    }>;
+    deleteObject(input: S3DeleteInput, options?: S3RequestOptions): Promise<Record<string, never>>;
+    copyObject(input: S3CopyInput, options?: S3RequestOptions): Promise<S3CopyOutput>;
+    listObjectsV2(input: S3ListInput, options?: S3RequestOptions): Promise<S3ListOutput>;
+}

package/dist/safe-fs/fs/s3/mock.js

@@ -0,0 +1,233 @@
+import { createHash } from "node:crypto";
+import { collectBytes } from "../../contracts/io.js";
+import { recordMockS3Head } from "./authority.js";
+import { S3ServiceError } from "./transport.js";
+function compareKeys(left, right) {
+    return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}
+export class MockS3Client {
+    capabilities = Object.freeze({ conditionalPut: true, conditionalCopy: true, conditionalDelete: true, streamingRead: true, streamingWrite: true });
+    buckets = new Map();
+    cursors = new Map();
+    history = [];
+    pageSize;
+    now;
+    authorize;
+    nextToken = 0;
+    constructor(options) {
+        this.pageSize = options.pageSize ?? 1000;
+        if (!Number.isInteger(this.pageSize) || this.pageSize < 1 || this.pageSize > 1000) {
+            throw new RangeError("pageSize must be an integer from 1 to 1000");
+        }
+        this.now = options.now ?? (() => new Date());
+        this.authorize = options.authorize;
+        for (const bucket of options.buckets)
+            this.buckets.set(bucket, new Map());
+    }
+    get requests() {
+        return structuredClone(this.history);
+    }
+    async begin(operation, input, options) {
+        if (options?.abortSignal?.aborted)
+            throw new S3ServiceError("AbortError", 499);
+        const request = { operation, input: structuredClone(input) };
+        this.history.push(structuredClone(request));
+        await this.authorize?.(request);
+        if (options?.abortSignal?.aborted)
+            throw new S3ServiceError("AbortError", 499);
+        if (!this.buckets.has(input.Bucket))
+            throw new S3ServiceError("NoSuchBucket", 404);
+        if ("Key" in input && (input.Key.length === 0 || Buffer.byteLength(input.Key) > 1024)) {
+            throw new S3ServiceError("InvalidArgument", 400);
+        }
+    }
+    bucket(name) {
+        const bucket = this.buckets.get(name);
+        if (!bucket)
+            throw new S3ServiceError("NoSuchBucket", 404);
+        return bucket;
+    }
+    object(input) {
+        const object = this.bucket(input.Bucket).get(input.Key);
+        if (!object)
+            throw new S3ServiceError("NoSuchKey", 404);
+        return object;
+    }
+    head(object) {
+        return {
+            ContentLength: object.body.byteLength,
+            ETag: object.etag,
+            LastModified: new Date(object.modified),
+            Metadata: { ...object.metadata },
+        };
+    }
+    store(body, metadata = {}) {
+        const metadataBytes = Object.entries(metadata).reduce((total, [key, value]) => total + Buffer.byteLength(key) + Buffer.byteLength(value), 0);
+        if (metadataBytes > 2048)
+            throw new S3ServiceError("MetadataTooLarge", 400);
+        return {
+            body: new Uint8Array(body),
+            etag: `"${createHash("md5").update(body).digest("hex")}"`,
+            modified: new Date(this.now()),
+            metadata: { ...metadata },
+        };
+    }
+    async headObject(input, options) {
+        await this.begin("headObject", input, options);
+        const output = this.head(this.object(input));
+        recordMockS3Head(output, input, this.bucket(input.Bucket));
+        return output;
+    }
+    async getObject(input, options) {
+        await this.begin("getObject", input, options);
+        const object = this.object(input);
+        return { ...this.head(object), Body: new Uint8Array(object.body) };
+    }
+    async putObject(input, options) {
+        if (!(input.Body instanceof Uint8Array))
+            throw new S3ServiceError("InvalidArgument", 400);
+        input = { ...input, Body: new Uint8Array(input.Body), ...(input.Metadata ? { Metadata: { ...input.Metadata } } : {}) };
+        await this.begin("putObject", input, options);
+        const bucket = this.bucket(input.Bucket);
+        const previous = bucket.get(input.Key);
+        if (input.IfMatch !== undefined && !previous)
+            throw new S3ServiceError("NoSuchKey", 404);
+        if ((input.IfNoneMatch === "*" && previous)
+            || (input.IfMatch !== undefined && previous?.etag !== input.IfMatch)) {
+            throw new S3ServiceError("PreconditionFailed", 412);
+        }
+        const object = this.store(input.Body, input.Metadata);
+        bucket.set(input.Key, object);
+        return { ETag: object.etag };
+    }
+    async getObjectStream(input, options) {
+        await this.begin("getObject", input, options);
+        const object = this.object(input);
+        if (input.IfMatch !== undefined && input.IfMatch !== object.etag)
+            throw new S3ServiceError("PreconditionFailed", 412);
+        let start = 0;
+        let end = object.body.length;
+        if (input.Range !== undefined) {
+            const range = /^bytes=(\d+)-(\d+)$/.exec(input.Range);
+            if (!range)
+                throw new S3ServiceError("InvalidArgument", 400);
+            start = Number(range[1]);
+            end = Math.min(Number(range[2]) + 1, end);
+            if (start >= end)
+                throw new S3ServiceError("InvalidRange", 416);
+        }
+        return {
+            ...this.head(object), ContentLength: end - start,
+            Body: (async function* () {
+                for (let offset = start; offset < end; offset += 64 * 1024) {
+                    if (options?.abortSignal?.aborted)
+                        throw new S3ServiceError("AbortError", 499);
+                    yield object.body.slice(offset, Math.min(offset + 64 * 1024, end));
+                }
+            })(),
+        };
+    }
+    async putObjectStream(input, options) {
+        const snapshot = { ...input, Body: new Uint8Array(), ...(input.Metadata ? { Metadata: { ...input.Metadata } } : {}) };
+        await this.begin("putObject", snapshot, options);
+        const body = await collectBytes(input.Body, { maxBytes: 5_000_000_000, ...(options?.abortSignal ? { signal: options.abortSignal } : {}) });
+        const bucket = this.bucket(input.Bucket);
+        const previous = bucket.get(input.Key);
+        if (input.IfMatch !== undefined && !previous)
+            throw new S3ServiceError("NoSuchKey", 404);
+        if ((input.IfNoneMatch === "*" && previous) || (input.IfMatch !== undefined && previous?.etag !== input.IfMatch)) {
+            throw new S3ServiceError("PreconditionFailed", 412);
+        }
+        const object = this.store(body, snapshot.Metadata);
+        bucket.set(input.Key, object);
+        return { ETag: object.etag };
+    }
+    async deleteObject(input, options) {
+        await this.begin("deleteObject", input, options);
+        const bucket = this.bucket(input.Bucket);
+        const previous = bucket.get(input.Key);
+        if (input.IfMatch !== undefined && !previous)
+            throw new S3ServiceError("NoSuchKey", 404);
+        if (previous && input.IfMatch !== undefined && input.IfMatch !== "*" && previous.etag !== input.IfMatch) {
+            throw new S3ServiceError("PreconditionFailed", 412);
+        }
+        bucket.delete(input.Key);
+        return {};
+    }
+    async copyObject(input, options) {
+        await this.begin("copyObject", input, options);
+        let decoded;
+        try {
+            decoded = decodeURIComponent(input.CopySource.replace(/^\//, ""));
+        }
+        catch {
+            throw new S3ServiceError("InvalidArgument", 400);
+        }
+        const separator = decoded.indexOf("/");
+        if (separator < 1)
+            throw new S3ServiceError("InvalidArgument", 400);
+        const source = this.object({ Bucket: decoded.slice(0, separator), Key: decoded.slice(separator + 1) });
+        if (input.CopySourceIfMatch !== undefined && input.CopySourceIfMatch !== source.etag) {
+            throw new S3ServiceError("PreconditionFailed", 412);
+        }
+        const bucket = this.bucket(input.Bucket);
+        if (input.IfNoneMatch === "*" && bucket.has(input.Key))
+            throw new S3ServiceError("PreconditionFailed", 412);
+        if (input.IfMatch !== undefined && bucket.get(input.Key)?.etag !== input.IfMatch)
+            throw new S3ServiceError("PreconditionFailed", 412);
+        const copy = this.store(source.body, input.MetadataDirective === "REPLACE" ? input.Metadata : source.metadata);
+        bucket.set(input.Key, copy);
+        return { CopyObjectResult: { ETag: copy.etag, LastModified: new Date(copy.modified) } };
+    }
+    async listObjectsV2(input, options) {
+        await this.begin("listObjectsV2", input, options);
+        const maxKeys = input.MaxKeys ?? 1000;
+        if (!Number.isInteger(maxKeys) || maxKeys < 0 || maxKeys > 1000)
+            throw new S3ServiceError("InvalidArgument", 400);
+        const prefix = input.Prefix ?? "";
+        const delimiter = input.Delimiter ?? "";
+        const scope = JSON.stringify([input.Bucket, prefix, delimiter]);
+        const cursor = input.ContinuationToken === undefined ? undefined : this.cursors.get(input.ContinuationToken);
+        if (input.ContinuationToken !== undefined && (!cursor || cursor.scope !== scope)) {
+            throw new S3ServiceError("InvalidArgument", 400, "invalid continuation token");
+        }
+        const entries = new Map();
+        for (const [key, object] of this.bucket(input.Bucket)) {
+            if (!key.startsWith(prefix))
+                continue;
+            const separator = delimiter === "" ? -1 : key.indexOf(delimiter, prefix.length);
+            if (separator >= 0) {
+                const commonPrefix = key.slice(0, separator + delimiter.length);
+                entries.set(commonPrefix, commonPrefix);
+            }
+            else {
+                entries.set(key, { Key: key, Size: object.body.byteLength, ETag: object.etag, LastModified: new Date(object.modified) });
+            }
+        }
+        const ordered = [...entries.keys()].sort(compareKeys)
+            .filter((key) => cursor === undefined || compareKeys(key, cursor.after) > 0);
+        const selected = ordered.slice(0, Math.min(maxKeys, this.pageSize));
+        const contents = [];
+        const prefixes = [];
+        for (const key of selected) {
+            const entry = entries.get(key);
+            if (typeof entry === "string")
+                prefixes.push({ Prefix: entry });
+            else if (entry)
+                contents.push(entry);
+        }
+        const truncated = maxKeys > 0 && selected.length < ordered.length;
+        let token;
+        if (truncated) {
+            token = `mock-s3-cursor-${++this.nextToken}`;
+            this.cursors.set(token, { scope, after: selected[selected.length - 1] });
+        }
+        return {
+            Contents: contents,
+            CommonPrefixes: prefixes,
+            KeyCount: selected.length,
+            IsTruncated: truncated,
+            ...(token === undefined ? {} : { NextContinuationToken: token }),
+        };
+    }
+}

package/dist/safe-fs/fs/s3/registry.d.ts

@@ -0,0 +1,10 @@
+import type { FileStat, FileSystem, FsOptions, EntryComparison } from "../../contracts/filesystem.js";
+import type { EntryView } from "../mount/comparison.js";
+export interface OwnedS3Entry {
+    readonly storage: object;
+    readonly key: string;
+}
+export declare function recordS3Observation(filesystem: FileSystem, path: string, stat: FileStat, entry: OwnedS3Entry): void;
+export declare function registerS3EntryOwner(filesystem: FileSystem, normalize: (path: string) => string, intact: () => boolean, baseComparison: NonNullable<FileSystem["compareEntry"]>, comparison?: NonNullable<FileSystem["compareEntry"]>): void;
+export declare function getOwnedS3Entry(view: EntryView): OwnedS3Entry | undefined;
+export declare function compareOwnedS3Entries(own: EntryView, peer: EntryView, options: FsOptions): Promise<EntryComparison>;

package/dist/safe-fs/fs/s3/registry.js

@@ -0,0 +1,71 @@
+import { FsError } from "../../contracts/errors.js";
+import { assertCallbackAuthorityAllowed } from "../mount/comparison.js";
+const observedStats = new WeakMap();
+const entries = new WeakMap();
+const comparisons = new WeakMap();
+const configuredComparisons = new WeakMap();
+export function recordS3Observation(filesystem, path, stat, entry) {
+    observedStats.set(stat, { filesystem, path, entry });
+}
+export function registerS3EntryOwner(filesystem, normalize, intact, baseComparison, comparison) {
+    comparisons.set(filesystem, baseComparison);
+    if (comparison)
+        configuredComparisons.set(filesystem, comparison);
+    entries.set(filesystem, view => {
+        if (!intact())
+            return undefined;
+        const observation = observedStats.get(view.stat);
+        return observation?.filesystem === filesystem && observation.path === normalize(view.path) ? observation.entry : undefined;
+    });
+}
+export function getOwnedS3Entry(view) {
+    return entries.get(view.filesystem)?.(view);
+}
+export async function compareOwnedS3Entries(own, peer, options) {
+    options.signal?.throwIfAborted();
+    let explicit = false;
+    let answer = "unknown";
+    const visited = new Set();
+    for (const [left, right] of [[own, peer], [peer, own]]) {
+        const baseComparison = comparisons.get(left.filesystem);
+        if (!baseComparison || visited.has(left.filesystem))
+            continue;
+        visited.add(left.filesystem);
+        const current = left.filesystem.compareEntry;
+        const comparison = current === baseComparison ? configuredComparisons.get(left.filesystem) : current;
+        if (current === baseComparison && comparison === undefined)
+            continue;
+        explicit = true;
+        if (comparison === undefined)
+            continue;
+        options.signal?.throwIfAborted();
+        if (typeof comparison !== "function") {
+            throw new FsError("EIO", { path: own.path, dest: peer.path, message: "invalid explicit S3 comparison method" });
+        }
+        assertCallbackAuthorityAllowed();
+        const result = await comparison.call(left.filesystem, left.path, right.filesystem, right.path, options);
+        options.signal?.throwIfAborted();
+        if (result !== "same" && result !== "distinct" && result !== "unknown") {
+            throw new FsError("EIO", { path: own.path, dest: peer.path, message: "invalid explicit S3 comparison" });
+        }
+        if (result === "unknown")
+            continue;
+        if (answer !== "unknown" && answer !== result) {
+            throw new FsError("EIO", { path: own.path, dest: peer.path, message: "conflicting explicit S3 comparisons" });
+        }
+        answer = result;
+    }
+    const left = getOwnedS3Entry(own);
+    options.signal?.throwIfAborted();
+    const right = getOwnedS3Entry(peer);
+    options.signal?.throwIfAborted();
+    const same = left && right && left.storage === right.storage && left.key === right.key;
+    if (same && answer === "distinct") {
+        throw new FsError("EIO", { path: own.path, dest: peer.path, message: "explicit S3 comparison contradicts a known alias" });
+    }
+    if (same)
+        return "same";
+    if (explicit)
+        return answer;
+    return left && right ? "distinct" : "unknown";
+}

package/dist/safe-fs/fs/s3/transport.d.ts

@@ -0,0 +1,103 @@
+export interface S3RequestOptions {
+    readonly abortSignal?: AbortSignal;
+}
+export interface S3ObjectInput {
+    readonly Bucket: string;
+    readonly Key: string;
+}
+export interface S3HeadOutput {
+    readonly ContentLength?: number | undefined;
+    readonly LastModified?: Date | undefined;
+    readonly ETag?: string | undefined;
+    readonly Metadata?: Record<string, string> | undefined;
+}
+export type S3Body = Uint8Array | AsyncIterable<Uint8Array> | {
+    transformToByteArray(): Promise<Uint8Array>;
+};
+export interface S3GetOutput extends S3HeadOutput {
+    readonly Body?: S3Body | undefined;
+}
+export interface S3StreamGetInput extends S3ObjectInput {
+    readonly Range?: string;
+    readonly IfMatch?: string;
+}
+export interface S3StreamGetOutput extends S3HeadOutput {
+    readonly Body: AsyncIterable<Uint8Array>;
+}
+export interface S3StreamPutInput extends Omit<S3PutInput, "Body"> {
+    readonly Body: AsyncIterable<Uint8Array>;
+}
+export interface S3PutInput extends S3ObjectInput {
+    readonly Body: Uint8Array;
+    readonly IfMatch?: string;
+    readonly IfNoneMatch?: "*";
+    readonly Metadata?: Record<string, string>;
+}
+export interface S3DeleteInput extends S3ObjectInput {
+    readonly IfMatch?: string;
+}
+export interface S3CopyInput extends S3ObjectInput {
+    readonly CopySource: string;
+    readonly CopySourceIfMatch?: string;
+    readonly IfNoneMatch?: "*";
+    readonly IfMatch?: string;
+    readonly MetadataDirective?: "COPY" | "REPLACE";
+    readonly Metadata?: Record<string, string>;
+}
+export interface S3CopyOutput {
+    readonly CopyObjectResult?: {
+        readonly ETag?: string | undefined;
+        readonly LastModified?: Date | undefined;
+    } | undefined;
+}
+export interface S3ListInput {
+    readonly Bucket: string;
+    readonly Prefix?: string;
+    readonly Delimiter?: string;
+    readonly MaxKeys?: number;
+    readonly ContinuationToken?: string;
+}
+export interface S3ObjectSummary {
+    readonly Key?: string | undefined;
+    readonly Size?: number | undefined;
+    readonly ETag?: string | undefined;
+    readonly LastModified?: Date | undefined;
+}
+export interface S3ListOutput {
+    readonly Contents?: readonly S3ObjectSummary[] | undefined;
+    readonly CommonPrefixes?: readonly {
+        readonly Prefix?: string | undefined;
+    }[] | undefined;
+    readonly IsTruncated?: boolean | undefined;
+    readonly NextContinuationToken?: string | undefined;
+    readonly KeyCount?: number | undefined;
+}
+export interface S3Client {
+    getObjectStream?(input: S3StreamGetInput, options?: S3RequestOptions): Promise<S3StreamGetOutput>;
+    putObjectStream?(input: S3StreamPutInput, options?: S3RequestOptions): Promise<unknown>;
+    headObject(input: S3ObjectInput, options?: S3RequestOptions): Promise<S3HeadOutput>;
+    getObject(input: S3ObjectInput, options?: S3RequestOptions): Promise<S3GetOutput>;
+    putObject(input: S3PutInput, options?: S3RequestOptions): Promise<unknown>;
+    deleteObject(input: S3DeleteInput, options?: S3RequestOptions): Promise<unknown>;
+    copyObject(input: S3CopyInput, options?: S3RequestOptions): Promise<S3CopyOutput>;
+    listObjectsV2(input: S3ListInput, options?: S3RequestOptions): Promise<S3ListOutput>;
+}
+export interface S3TransportCapabilities {
+    readonly streamingRead?: boolean;
+    readonly streamingWrite?: boolean;
+    readonly conditionalPut?: boolean;
+    readonly conditionalCopy?: boolean;
+    readonly conditionalDelete?: boolean;
+}
+export interface S3Transport extends S3Client {
+    readonly capabilities?: S3TransportCapabilities;
+}
+export declare function createS3Transport(client: S3Client, capabilities?: S3TransportCapabilities): S3Transport;
+export declare class S3ServiceError extends Error {
+    readonly code: string;
+    readonly $metadata: {
+        readonly httpStatusCode: number;
+    };
+    constructor(code: string, status: number, message?: string);
+}
+export declare function encodeCopySource(bucket: string, key: string): string;