git-fs-s3 0.3.5

package/dist/index.d.ts

@@ -0,0 +1,373 @@
+import { O as ObjectStore, G as GitFsClient, a as GitFsOptions, b as ObjectStat, L as ListOptions, c as ListResult } from './types-QgIkUR_q.js';
+export { S as Stat } from './types-QgIkUR_q.js';
+
+interface CacheOptions {
+    /** Maximum bytes of object data held in memory. Default 50 MiB. */
+    maxBytes?: number;
+    /**
+     * Largest single entry admitted to the cache. Defaults to a tenth of
+     * `maxBytes` so one huge packfile cannot evict the whole working set.
+     */
+    maxEntryBytes?: number;
+    /** Entry time-to-live in milliseconds. Default 60 000. */
+    ttlMs?: number;
+    /**
+     * Override the TTL for a specific key (get/head) or list prefix (list),
+     * in milliseconds. Return `undefined` to fall back to `ttlMs`. Git refs
+     * (`refs/heads/<branch>`, `HEAD`) are mutable — the same key's value
+     * changes on every push — unlike content-addressed object keys, which
+     * never change for a given key and are safe to cache for the full
+     * `ttlMs`. Without this, a long `ttlMs` tuned for objects also caches
+     * ref reads that long, so a warm process can keep serving a
+     * pre-push ref value for the rest of that TTL even though nothing
+     * changed *this* process's own cache (see `invalidate`) — it just never
+     * knew to. Give ref-like keys a short override (a few seconds) instead:
+     * a ref read is one small object, so re-reading it far more often than
+     * `ttlMs` is cheap, and every read downstream of a fresh ref (tree,
+     * commit, blob — all keyed by the sha it resolves to) still gets the
+     * full-length cache/coalescing benefit.
+     */
+    ttlForKey?: (key: string) => number | undefined;
+    /**
+     * Also cache "key does not exist" results. Loose-object probes on packed
+     * repositories are almost always misses, so this saves many round trips —
+     * but only enable it when a single process is the only writer, otherwise
+     * another instance's push can be masked for up to `ttlMs`.
+     */
+    cacheMisses?: boolean;
+    /**
+     * Also cache `list()` results (directory listings and `limit: 1`
+     * existence probes). Writes through this store keep cached listings
+     * consistent; after writing to the backend by any other means, call
+     * `invalidate()` with the affected prefix. Default false.
+     */
+    cacheLists?: boolean;
+    /**
+     * Collapse concurrent `get`/`head`/`list` calls for the same key into a
+     * single backend request. Default true.
+     */
+    coalesce?: boolean;
+    /** Called when a read is answered from cache. */
+    onHit?: (key: string) => void;
+    /** Called when a read has to go to the backing store. */
+    onMiss?: (key: string) => void;
+}
+/** An {@link ObjectStore} wrapper that also supports explicit invalidation. */
+interface CachedObjectStore extends ObjectStore {
+    /**
+     * Drop every cached entry — contents, misses, and listings — whose key
+     * falls under `prefix` (exact keys included). Call this after the backing
+     * store was modified by something other than this wrapper.
+     */
+    invalidate(prefix: string): void;
+}
+/**
+ * Wrap an {@link ObjectStore} with an in-process LRU read cache.
+ *
+ * Git object keys are content-addressed and therefore immutable, which makes
+ * them ideal cache entries; mutable keys (refs, packed-refs) are bounded by
+ * `ttlMs`. Writes and deletes through this wrapper invalidate their key and
+ * any cached listings they affect — with one asymmetry: a non-empty `limit: 1`
+ * probe (a "directory exists" answer) survives writes underneath it, because
+ * adding a key below a prefix cannot make that prefix stop existing, while
+ * empty probes and full listings are always dropped.
+ */
+declare function createCachedStore(store: ObjectStore, options?: CacheOptions): CachedObjectStore;
+
+/**
+ * Edge-compatible utilities replacing node:crypto, node:zlib, and Buffer.
+ *
+ * Every function here uses only Web APIs (SubtleCrypto, CompressionStream,
+ * TextEncoder/TextDecoder) — no Node built-ins. They work on Cloudflare
+ * Workers, Vercel Edge, Deno Deploy, and Node >= 18.
+ */
+/**
+ * Encode a UTF-8 string to bytes.
+ *
+ * Return type pinned to `Uint8Array<ArrayBuffer>` (not the bare `Uint8Array`,
+ * whose default type argument differs across TypeScript versions) so it's
+ * always assignable to Fetch API `BodyInit` regardless of a consumer's own
+ * TypeScript/lib version.
+ */
+declare function encodeUtf8(data: string): Uint8Array<ArrayBuffer>;
+/** Decode bytes as UTF-8. */
+declare function decodeUtf8(data: Uint8Array): string;
+/** Decode bytes as ASCII. */
+declare function decodeAscii(data: Uint8Array): string;
+/** Concatenate any number of Uint8Arrays into one. */
+declare function concat(...parts: Uint8Array[]): Uint8Array<ArrayBuffer>;
+/** Uint8Array → lowercase hex string. */
+declare function toHex(data: Uint8Array): string;
+/** Uint8Array → base64 string. */
+declare function toBase64(data: Uint8Array): string;
+/** Hex string → Uint8Array. */
+declare function fromHex(hex: string): Uint8Array<ArrayBuffer>;
+/** SHA-1 hash via Web Crypto API. Returns a hex string. */
+declare function sha1(data: Uint8Array | string): Promise<string>;
+/**
+ * Deflate compress via the CompressionStream Web API.
+ * Falls back to throwing if CompressionStream is unavailable (very old runtimes).
+ */
+declare function deflate(data: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+/** Check if a Uint8Array contains a null byte. */
+declare function hasNullByte(data: Uint8Array): boolean;
+/**
+ * Read a blob as text or binary metadata — the edge-compatible replacement
+ * for the `Buffer.from(blob)` pattern used throughout diff.ts and history.ts.
+ */
+declare function readBlobContent(blob: Uint8Array): {
+    isBinary: boolean;
+    text: string;
+    bytes: Uint8Array;
+};
+
+/**
+ * Node-style filesystem error carrying a `code` property, which is what
+ * isomorphic-git inspects to distinguish "file not found" from real failures.
+ */
+declare class FsError extends Error {
+    readonly code: string;
+    readonly syscall: string;
+    readonly path: string;
+    constructor(code: string, syscall: string, path: string);
+}
+
+/**
+ * Git-server error types carrying an HTTP status and a retryability flag, so
+ * transport layers can map internal failures to responses without inspecting
+ * messages. Extend {@link GitError} for app-specific cases (storage backends,
+ * quota, …) and {@link formatErrorResponse} keeps working for them.
+ */
+declare class GitError extends Error {
+    statusCode: number;
+    retryable: boolean;
+    constructor(message: string, statusCode?: number, retryable?: boolean);
+    toJSON(): Record<string, unknown>;
+}
+/** A file/directory path not found within a tree (404). */
+declare class GitPathNotFoundError extends GitError {
+    constructor(message: string);
+}
+/** A git object not found (404). */
+declare class GitObjectNotFoundError extends GitError {
+    constructor(message: string);
+}
+/** A ref (branch/tag) not found (404). */
+declare class GitRefNotFoundError extends GitError {
+    constructor(message: string);
+}
+/** The repository itself not found (404). */
+declare class GitRepositoryNotFoundError extends GitError {
+    constructor(message: string);
+}
+interface MergeConflictDetail {
+    file: string;
+    baseLines?: string[];
+    sourceLines?: string[];
+    targetLines?: string[];
+}
+/** A merge conflict (409), carrying per-file conflict detail. */
+declare class GitConflictError extends GitError {
+    conflicts: MergeConflictDetail[];
+    constructor(message: string, conflicts?: MergeConflictDetail[]);
+    toJSON(): Record<string, unknown>;
+}
+/** Authentication failed (401). */
+declare class GitAuthenticationError extends GitError {
+    constructor(message: string);
+}
+/** Authorization failed (403). */
+declare class GitAuthorizationError extends GitError {
+    constructor(message: string);
+}
+/** Too many failed attempts (429). */
+declare class GitRateLimitError extends GitError {
+    constructor(message: string);
+}
+/** Malformed request (400). */
+declare class GitInvalidRequestError extends GitError {
+    constructor(message: string);
+}
+/** Git wire-protocol violation (400). */
+declare class GitProtocolError extends GitError {
+    constructor(message: string);
+}
+/**
+ * Map any error to an HTTP response shape. 401s carry the WWW-Authenticate
+ * header git clients need before they will prompt for credentials. Non-GitError
+ * failures are masked as opaque 500s — internal messages don't leak.
+ */
+declare function formatErrorResponse(error: unknown): {
+    status: number;
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+};
+
+/**
+ * The filesystem returned by {@link createGitFs}: the isomorphic-git client
+ * plus git-aware maintenance hooks.
+ */
+interface GitFs extends GitFsClient {
+    /**
+     * Probe, with one bounded list, whether `gitdir` contains any loose
+     * objects, and remember the answer. This is the only way a loose-object
+     * hint is ever created; call it before full-history walks (commit logs,
+     * reachability traversals) so fully packed repositories skip every
+     * guaranteed-miss loose-object read. A later loose write flips the hint
+     * back, so it cannot go stale mid-push.
+     */
+    detectLooseObjects(gitdir: string): Promise<void>;
+    /**
+     * Warm the cache with every pack file under `gitdir` in parallel (plus
+     * the loose-object hint) before a sequential history walk. Skipped when
+     * the pack directory holds more than `maxPacks * 2` entries — warming
+     * only helps when the cache budget actually fits the packs.
+     */
+    prefetchPacks(gitdir: string, options?: {
+        maxPacks?: number;
+    }): Promise<void>;
+    /**
+     * Clear fs-level state (loose-object hints) under `pathPrefix`, and
+     * forward to the store's `invalidate` when it has one. Call after the
+     * backing store was modified by something other than this fs.
+     */
+    invalidate(pathPrefix: string): void;
+}
+/**
+ * Create a promise-based filesystem client for isomorphic-git backed by an
+ * {@link ObjectStore}.
+ *
+ * Semantics:
+ * - Directories are implicit, as in object storage: `mkdir` is a no-op and a
+ *   directory "exists" whenever at least one key lives under its prefix.
+ * - Symbolic links are not supported (`readlink`/`symlink` throw). Bare
+ *   repositories never contain them.
+ * - Designed for bare, server-side repositories (`git.init({bare: true})`,
+ *   plumbing commands, ref updates). Worktree checkouts belong on a real disk.
+ */
+declare function createGitFs(store: ObjectStore, options?: GitFsOptions): GitFs;
+
+/**
+ * Git ref-name validation, mirroring isomorphic-git's own internal `isValidRef`
+ * character-class rules (the check `git.branch` and top-level `git.writeRef`
+ * run before touching disk).
+ *
+ * Several of isomorphic-git's OTHER ref-touching primitives — `git.commit`,
+ * `git.merge`, `git.deleteBranch`, and top-level `git.resolveRef`/
+ * `git.deleteRef` — do NOT run this check internally: they resolve straight
+ * through `fs.write`/`fs.rm(join(gitdir, ref))` with no jail to the gitdir.
+ * On a shared-storage server (many repos under one prefix or base directory),
+ * every branch/ref name that originates from request input must be validated
+ * against these predicates before it reaches any of those primitives —
+ * otherwise a `"../"`-laden name lets a caller with write access to any single
+ * repo read, corrupt, or delete another repo's ref/object files.
+ */
+/** Validates a fully-qualified ref (must start with refs/heads/ or refs/tags/). */
+declare function isSafeFullRefName(ref: string): boolean;
+/**
+ * Validates a bare branch name (no refs/ prefix). Rejects anything that looks
+ * like a full ref path — a name of `"refs/heads/x"` would otherwise sail
+ * through unprefixed at call sites that build `refs/heads/${name}` themselves
+ * (doubling the prefix into something that still resolves), or be used as-is
+ * at call sites that pass a name already containing `"refs/"` straight
+ * through. Also rejects 40-hex SHA-shaped values so a stored branch name can
+ * never be ambiguous with a commit SHA at write time; use
+ * {@link isSafeRefName} on read paths that accept both shapes.
+ */
+declare function isSafeBranchName(name: string): boolean;
+/** True for a full 40-hex-char commit SHA — the shape {@link isSafeBranchName} deliberately rejects. */
+declare function isFullSha(value: string): boolean;
+/**
+ * Validates a "ref" field that may name either a branch or a commit SHA it's
+ * pinned to — the shape read-path route params take (permalinks, raw links).
+ * Both shapes still go through the traversal check.
+ */
+declare function isSafeRefName(value: string): boolean;
+/**
+ * Validates a repo-relative file path from request input: relative, no `..`
+ * segments, no `.git/` prefix, no null bytes. Use this anywhere a path
+ * segment comes straight off a URL or form field rather than re-deriving the
+ * checks ad hoc.
+ */
+declare function isSafeRepoPath(p: string): boolean;
+/**
+ * Qualify a bare branch name to `refs/heads/<name>` before handing it to
+ * isomorphic-git. `resolveRef`/`expand` try several candidate paths in
+ * sequence for a bare name — `ref`, `refs/ref`, `refs/tags/ref`,
+ * `refs/heads/ref`, … — missing (and, against object storage, paying a real
+ * round trip for) the first three every time. For a branch-only ref model,
+ * skip straight to the winner. Left untouched: already-qualified refs,
+ * `"HEAD"` (its own first candidate, already optimal), and 40-hex oids
+ * (resolved locally by isomorphic-git with no I/O at all).
+ */
+declare function qualifyBranchRef(ref: string): string;
+
+/** Options accepted by {@link createRetryStore}. */
+interface RetryOptions {
+    /** Retries after the first attempt (total attempts = retries + 1). Default 3. */
+    retries?: number;
+    /** Backoff base delay in milliseconds, doubled each attempt. Default 100. */
+    initialDelayMs?: number;
+    /** Upper bound for the backoff base delay. Default 5000. */
+    maxDelayMs?: number;
+    /** Random jitter added to each delay, as a fraction of it. Default 0.3. */
+    jitter?: number;
+    /**
+     * Decide whether an error is worth retrying. The store contract maps
+     * "not found" to `null` rather than throwing, so any thrown error is a
+     * genuine failure; the default retries network faults, throttling, and
+     * HTTP 5xx responses.
+     */
+    isRetryable?: (error: unknown) => boolean;
+    /**
+     * Circuit breaker configuration, or `false` to disable. After `threshold`
+     * consecutive failures the store fails fast for `resetMs`, then lets one
+     * request probe the backend again. Defaults: 5 failures, 30 000 ms.
+     */
+    breaker?: false | {
+        threshold?: number;
+        resetMs?: number;
+    };
+    /** Called before each retry sleep; useful for logging/metrics. */
+    onRetry?: (info: {
+        key: string;
+        op: string;
+        attempt: number;
+        delayMs: number;
+    }) => void;
+}
+/**
+ * Thrown instead of calling the backend while the circuit breaker is open.
+ * Carries `code: "EUNAVAILABLE"` so callers can map it to a 503.
+ */
+declare class CircuitOpenError extends Error {
+    readonly code = "EUNAVAILABLE";
+    constructor();
+}
+/**
+ * Wrap an {@link ObjectStore} with retries (exponential backoff + jitter) and
+ * an optional per-instance circuit breaker.
+ *
+ * Place this decorator closest to the network store, underneath any cache:
+ * the cache then never stores transient failures, and callers coalesced onto
+ * one request share a single retried attempt.
+ */
+declare function createRetryStore(store: ObjectStore, options?: RetryOptions): ObjectStore;
+
+/**
+ * In-memory {@link ObjectStore}. Useful for tests, examples, and ephemeral
+ * repositories; also the reference implementation for the list/delimiter
+ * semantics other stores must match.
+ */
+declare class MemoryObjectStore implements ObjectStore {
+    private readonly objects;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, data: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<ObjectStat | null>;
+    list(prefix: string, options?: ListOptions): Promise<ListResult>;
+    /** Number of stored objects (test convenience, not part of ObjectStore). */
+    get size(): number;
+}
+
+export { type CacheOptions, type CachedObjectStore, CircuitOpenError, FsError, GitAuthenticationError, GitAuthorizationError, GitConflictError, GitError, type GitFs, GitFsClient, GitFsOptions, GitInvalidRequestError, GitObjectNotFoundError, GitPathNotFoundError, GitProtocolError, GitRateLimitError, GitRefNotFoundError, GitRepositoryNotFoundError, ListOptions, ListResult, MemoryObjectStore, type MergeConflictDetail, ObjectStat, ObjectStore, type RetryOptions, concat, createCachedStore, createGitFs, createRetryStore, decodeAscii, decodeUtf8, deflate, encodeUtf8, formatErrorResponse, fromHex, hasNullByte, isFullSha, isSafeBranchName, isSafeFullRefName, isSafeRefName, isSafeRepoPath, qualifyBranchRef, readBlobContent, sha1, toBase64, toHex };