git-fs-s3 0.3.5

package/dist/types-QgIkUR_q.d.cts

@@ -0,0 +1,121 @@
+/**
+ * Minimal key/value object-storage contract the git filesystem is built on.
+ *
+ * Implement this interface to back git with any storage system. Two
+ * implementations ship with the package: {@link ../stores/memory.MemoryObjectStore}
+ * and {@link ../stores/s3.S3ObjectStore}.
+ */
+interface ObjectStore {
+    /** Return the object's bytes, or `null` if the key does not exist. */
+    get(key: string): Promise<Uint8Array | null>;
+    /** Create or overwrite the object at `key`. */
+    put(key: string, data: Uint8Array): Promise<void>;
+    /** Delete the object at `key`. Must succeed silently if it does not exist. */
+    delete(key: string): Promise<void>;
+    /** Return object metadata without fetching the body, or `null` if absent. */
+    head(key: string): Promise<ObjectStat | null>;
+    /**
+     * List keys under `prefix`.
+     *
+     * With `delimiter: "/"` the result groups keys the way S3 ListObjectsV2
+     * does: `objects` holds direct children, `prefixes` holds the common
+     * prefixes ("subdirectories"). With `limit`, implementations may return
+     * early after finding that many entries (used for cheap existence checks).
+     */
+    list(prefix: string, options?: ListOptions): Promise<ListResult>;
+}
+interface ObjectStat {
+    size: number;
+}
+interface ListOptions {
+    delimiter?: string;
+    limit?: number;
+}
+interface ListResult {
+    objects: {
+        key: string;
+        size: number;
+    }[];
+    prefixes: string[];
+}
+/** Options accepted by {@link ../git-fs.createGitFs}. */
+interface GitFsOptions {
+    /**
+     * Key prefix all paths are stored under, e.g. `"repos/alice/blog"`.
+     * Defaults to `""` (paths map directly to keys).
+     */
+    prefix?: string;
+    /**
+     * Track, per git directory, whether any loose objects exist at all.
+     * Fully packed repositories then skip the doomed round trip probing a
+     * loose-object path that is guaranteed to miss — but only after an
+     * explicit `detectLooseObjects(gitdir)` call has registered the gitdir.
+     * Default false.
+     */
+    looseObjectHints?: boolean;
+    /**
+     * Paths (relative to the fs, before `prefix` is applied) that are known
+     * never to exist; `readFile`/`stat` answer ENOENT for them with zero
+     * store calls. Useful for files git probes on every operation but this
+     * backend never writes, such as `packed-refs` or `shallow` under a known
+     * gitdir layout. Match precisely — a plain suffix check is wrong, since
+     * e.g. `refs/heads/packed-refs` is a legal branch ref.
+     */
+    isStructurallyAbsent?: (path: string) => boolean;
+    /** Time-to-live for loose-object hints in milliseconds. Default 3 600 000. */
+    hintTtlMs?: number;
+    /** Diagnostic sink for notable fs events (hint detection results). */
+    onNote?: (message: string) => void;
+}
+type Encoding = "utf8";
+interface ReadFileOptions {
+    encoding?: Encoding;
+}
+interface WriteFileOptions {
+    encoding?: Encoding;
+    mode?: number;
+}
+/**
+ * The stat shape isomorphic-git expects. Object storage has no inodes,
+ * owners, or modification times, so numeric fields are zero.
+ */
+interface Stat {
+    type: "file" | "dir";
+    mode: number;
+    size: number;
+    ino: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    uid: number;
+    gid: number;
+    dev: number;
+    mtime: Date;
+    ctime: Date;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+/**
+ * Promise-based filesystem client compatible with isomorphic-git's `fs`
+ * option. Declared locally so the package has no dependency on
+ * isomorphic-git itself.
+ */
+interface GitFsClient {
+    promises: {
+        readFile(filepath: string, options?: ReadFileOptions | Encoding): Promise<Uint8Array | string>;
+        writeFile(filepath: string, data: Uint8Array | string, options?: WriteFileOptions | Encoding): Promise<void>;
+        unlink(filepath: string): Promise<void>;
+        readdir(dirpath: string): Promise<string[]>;
+        mkdir(dirpath: string, options?: {
+            mode?: number;
+        }): Promise<void>;
+        rmdir(dirpath: string): Promise<void>;
+        stat(filepath: string): Promise<Stat>;
+        lstat(filepath: string): Promise<Stat>;
+        readlink(filepath: string): Promise<never>;
+        symlink(target: string, filepath: string): Promise<never>;
+        chmod(filepath: string, mode: number): Promise<void>;
+    };
+}
+
+export type { GitFsClient as G, ListOptions as L, ObjectStore as O, Stat as S, GitFsOptions as a, ObjectStat as b, ListResult as c };

package/dist/types-QgIkUR_q.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Minimal key/value object-storage contract the git filesystem is built on.
+ *
+ * Implement this interface to back git with any storage system. Two
+ * implementations ship with the package: {@link ../stores/memory.MemoryObjectStore}
+ * and {@link ../stores/s3.S3ObjectStore}.
+ */
+interface ObjectStore {
+    /** Return the object's bytes, or `null` if the key does not exist. */
+    get(key: string): Promise<Uint8Array | null>;
+    /** Create or overwrite the object at `key`. */
+    put(key: string, data: Uint8Array): Promise<void>;
+    /** Delete the object at `key`. Must succeed silently if it does not exist. */
+    delete(key: string): Promise<void>;
+    /** Return object metadata without fetching the body, or `null` if absent. */
+    head(key: string): Promise<ObjectStat | null>;
+    /**
+     * List keys under `prefix`.
+     *
+     * With `delimiter: "/"` the result groups keys the way S3 ListObjectsV2
+     * does: `objects` holds direct children, `prefixes` holds the common
+     * prefixes ("subdirectories"). With `limit`, implementations may return
+     * early after finding that many entries (used for cheap existence checks).
+     */
+    list(prefix: string, options?: ListOptions): Promise<ListResult>;
+}
+interface ObjectStat {
+    size: number;
+}
+interface ListOptions {
+    delimiter?: string;
+    limit?: number;
+}
+interface ListResult {
+    objects: {
+        key: string;
+        size: number;
+    }[];
+    prefixes: string[];
+}
+/** Options accepted by {@link ../git-fs.createGitFs}. */
+interface GitFsOptions {
+    /**
+     * Key prefix all paths are stored under, e.g. `"repos/alice/blog"`.
+     * Defaults to `""` (paths map directly to keys).
+     */
+    prefix?: string;
+    /**
+     * Track, per git directory, whether any loose objects exist at all.
+     * Fully packed repositories then skip the doomed round trip probing a
+     * loose-object path that is guaranteed to miss — but only after an
+     * explicit `detectLooseObjects(gitdir)` call has registered the gitdir.
+     * Default false.
+     */
+    looseObjectHints?: boolean;
+    /**
+     * Paths (relative to the fs, before `prefix` is applied) that are known
+     * never to exist; `readFile`/`stat` answer ENOENT for them with zero
+     * store calls. Useful for files git probes on every operation but this
+     * backend never writes, such as `packed-refs` or `shallow` under a known
+     * gitdir layout. Match precisely — a plain suffix check is wrong, since
+     * e.g. `refs/heads/packed-refs` is a legal branch ref.
+     */
+    isStructurallyAbsent?: (path: string) => boolean;
+    /** Time-to-live for loose-object hints in milliseconds. Default 3 600 000. */
+    hintTtlMs?: number;
+    /** Diagnostic sink for notable fs events (hint detection results). */
+    onNote?: (message: string) => void;
+}
+type Encoding = "utf8";
+interface ReadFileOptions {
+    encoding?: Encoding;
+}
+interface WriteFileOptions {
+    encoding?: Encoding;
+    mode?: number;
+}
+/**
+ * The stat shape isomorphic-git expects. Object storage has no inodes,
+ * owners, or modification times, so numeric fields are zero.
+ */
+interface Stat {
+    type: "file" | "dir";
+    mode: number;
+    size: number;
+    ino: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    uid: number;
+    gid: number;
+    dev: number;
+    mtime: Date;
+    ctime: Date;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+/**
+ * Promise-based filesystem client compatible with isomorphic-git's `fs`
+ * option. Declared locally so the package has no dependency on
+ * isomorphic-git itself.
+ */
+interface GitFsClient {
+    promises: {
+        readFile(filepath: string, options?: ReadFileOptions | Encoding): Promise<Uint8Array | string>;
+        writeFile(filepath: string, data: Uint8Array | string, options?: WriteFileOptions | Encoding): Promise<void>;
+        unlink(filepath: string): Promise<void>;
+        readdir(dirpath: string): Promise<string[]>;
+        mkdir(dirpath: string, options?: {
+            mode?: number;
+        }): Promise<void>;
+        rmdir(dirpath: string): Promise<void>;
+        stat(filepath: string): Promise<Stat>;
+        lstat(filepath: string): Promise<Stat>;
+        readlink(filepath: string): Promise<never>;
+        symlink(target: string, filepath: string): Promise<never>;
+        chmod(filepath: string, mode: number): Promise<void>;
+    };
+}
+
+export type { GitFsClient as G, ListOptions as L, ObjectStore as O, Stat as S, GitFsOptions as a, ObjectStat as b, ListResult as c };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "git-fs-s3",
+  "version": "0.3.5",
+  "description": "isomorphic-git filesystem backend for S3-compatible object storage (AWS S3, Cloudflare R2, MinIO) — run git servers without a disk",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./s3": {
+      "types": "./dist/s3.d.ts",
+      "import": "./dist/s3.js",
+      "require": "./dist/s3.cjs"
+    },
+    "./ops": {
+      "types": "./dist/ops.d.ts",
+      "import": "./dist/ops.js",
+      "require": "./dist/ops.cjs"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js",
+      "require": "./dist/http.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --write src/ test/",
+    "format": "biome format --write src/ test/",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "git",
+    "isomorphic-git",
+    "s3",
+    "r2",
+    "cloudflare-r2",
+    "object-storage",
+    "serverless",
+    "git-server",
+    "filesystem",
+    "fs"
+  ],
+  "author": "Nandan Varma",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nandan-varma/git-fs-s3.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nandan-varma/git-fs-s3/issues"
+  },
+  "homepage": "https://github.com/nandan-varma/git-fs-s3#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "lru-cache": "^11.2.1"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "isomorphic-git": ">=1.24.0",
+    "diff": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "isomorphic-git": {
+      "optional": true
+    },
+    "diff": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.750.0",
+    "@biomejs/biome": "^2.3.8",
+    "@types/node": "^22.15.21",
+    "isomorphic-git": "^1.27.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3",
+    "diff": "^7.0.0",
+    "@types/diff": "^7.0.0"
+  },
+  "allowScripts": {
+    "esbuild@0.27.7": true
+  }
+}