git-fs-s3 0.8.0 → 0.10.0

package/dist/types/ops/history.d.ts

@@ -1,36 +1,35 @@
 import { type TreeEntry } from "./tree.js";
 import { type OpsHooks, type Repo } from "./types.js";
+/** How far back history walks look by default (commit count). */
+export declare const HISTORY_WALK_DEPTH = 400;
+export interface GitIdentity {
+    name: string;
+    email: string;
+    timestamp: number;
+    timezoneOffset: number;
+}
 export interface CommitInfo {
     oid: string;
     commit: {
         message: string;
         tree: string;
         parent: string[];
-        author: {
-            name: string;
-            email: string;
-            timestamp: number;
-            timezoneOffset: number;
-        };
-        committer: {
-            name: string;
-            email: string;
-            timestamp: number;
-            timezoneOffset: number;
-        };
+        author: GitIdentity;
+        committer: GitIdentity;
     };
     payload: string;
 }
-/**
- * Resolve a branch name / full ref / sha to its commit. The ref not
- * resolving (unborn branch, genuinely empty repo) and the ref resolving but
- * its commit object being unreadable (storage inconsistency — see
- * `wrapMissingObject` above) are different failures with different meanings,
- * so only the first is left as a raw isomorphic-git NotFoundError for
- * callers to treat as "empty"; the second is wrapped into
- * GitObjectNotFoundError specifically so it can't be mistaken for the first
- * by an `isNotFound`-style check downstream (see getTreeFromRef/getCommitLog).
- */
+/** The display summary of a commit (history lists, "last commit" columns). */
+export interface CommitSummary {
+    sha: string;
+    message: string;
+    authorName: string;
+    authorEmail: string;
+    /** ISO 8601 author date. */
+    createdAt: string;
+}
+export declare function summarizeCommit(commit: CommitInfo): CommitSummary;
+/** Resolve a branch name / full ref / sha to its commit. */
 export declare function resolveCommit(repo: Repo, ref: string): Promise<{
     oid: string;
     commit: import("isomorphic-git").CommitObject;
@@ -44,40 +43,28 @@ export declare function getCommit(repo: Repo, sha: string): Promise<CommitInfo>;
 export interface CommitLogOptions {
     ref: string;
     depth?: number;
-    /**
-     * Pass the head sha when the caller already resolved `ref` — resolveRef
-     * tries several candidate paths in sequence and misses the first few every
-     * time for a normal branch name, which is pure waste when the sha is known.
-     */
+    /** The ref's commit, when the caller already resolved it (saves a lookup). */
     knownHeadSha?: string;
 }
 /**
- * The commit chain from a ref, newest first. Walking is inherently sequential
- * (each commit's oid is only discoverable by reading its child first) and
- * network-round-trip-bound against object storage, so the deepest walk seen
- * per head is memoized in `hooks.resultCache` and sliced for shallower or
- * repeated requests — don't bypass this by calling `git.log` directly.
+ * The commit chain from a ref, newest first; [] when the ref doesn't exist.
+ * Walking is sequential and round-trip-bound on object storage, so the
+ * deepest walk seen per head is memoized in `hooks.resultCache` and sliced
+ * for shallower requests.
  */
 export declare function getCommitLog(repo: Repo, options: CommitLogOptions, hooks?: OpsHooks): Promise<CommitInfo[]>;
-/** A file at a ref, decoded for display: utf8 text or base64 when binary. */
-export declare function getFileFromRef(repo: Repo, filePath: string, ref: string, hooks?: OpsHooks): Promise<{
-    content: string;
-    size: number;
-    isBinary: boolean;
-}>;
 /**
  * List a directory at the tip of a ref. Throws GitRefNotFoundError when the
- * ref doesn't resolve (including an empty repo's unborn branch) and
- * GitPathNotFoundError when `treePath` doesn't exist. Results are memoized per
- * head sha (auto-invalidates on push).
+ * ref doesn't resolve and GitPathNotFoundError when `treePath` doesn't exist.
+ * Memoized per head sha.
  */
 export declare function getTreeFromRef(repo: Repo, options: {
     ref: string;
     treePath?: string;
 }, hooks?: OpsHooks): Promise<TreeEntry[]>;
 /**
- * A page of commit history from a branch tip. Memoized per head sha; builds
- * on {@link getCommitLog}'s walk cache for the underlying chain.
+ * A page of commit history from a ref tip; [] when the ref doesn't exist.
+ * Pages are slices of {@link getCommitLog}'s memoized walk.
  */
 export declare function getCommitHistory(repo: Repo, options: {
     ref: string;

package/dist/types/ops/index.d.ts

@@ -1,10 +1,11 @@
 export { assertBranchExists, assertSafeBranchName, type Branch, createBranchFrom, deleteBranchByName, listBranches, resolveLooseRefFast, } from "./branch.js";
 export { authorNow, type CommitAuthor, commitFilesToBare, deleteFileFromBare, writeCommitToBare, } from "./commit.js";
-export { type DiffFile, type DiffResult, getCommitDiff, getDiffBetweenRefs, MAX_DIFF_TEXT_BYTES, } from "./diff.js";
-export { BANNER_WALK_DEPTH, type FileHistoryEntry, type FileHistoryResult, getFileHistory, HISTORY_WALK_DEPTH, } from "./file-history.js";
-export { type CommitInfo, type CommitLogOptions, getBlob, getCommit, getCommitHistory, getCommitLog, getFileContent, getFileFromRef, getTreeFromRef, resolveCommit, } from "./history.js";
-export { getLastCommitsForTree, type LastCommitInfo, } from "./last-commit.js";
+export { type DiffEntry, type DiffFile, type DiffResult, getCommitDiff, getDiffBetweenRefs, MAX_DIFF_TEXT_BYTES, } from "./diff.js";
+export { BANNER_WALK_DEPTH, type FileHistoryResult, getFileHistory, } from "./file-history.js";
+export { type CommitInfo, type CommitLogOptions, type CommitSummary, type GitIdentity, getBlob, getCommit, getCommitHistory, getCommitLog, getFileContent, getTreeFromRef, HISTORY_WALK_DEPTH, resolveCommit, summarizeCommit, } from "./history.js";
+export { getLastCommitsForTree } from "./last-commit.js";
 export { analyzeMerge, fastForwardMerge, type MergeAnalysis } from "./merge.js";
 export { withPackedWrites } from "./packed-writes.js";
+export { getSubmodules, parseGitmodules, type SubmoduleConfig, } from "./submodules.js";
 export { deleteFromTree, findTreeEntry, listTreeEntries, type TreeEntry, upsertTree, } from "./tree.js";
 export { type IsoGitFs, type OpsHooks, type Repo, type ResultCache, resultKeyPrefixes, } from "./types.js";

package/dist/types/ops/last-commit.d.ts

@@ -1,11 +1,5 @@
+import { type CommitSummary } from "./history.js";
 import type { OpsHooks, Repo } from "./types.js";
-export interface LastCommitInfo {
-    sha: string;
-    message: string;
-    authorName: string;
-    authorEmail: string;
-    createdAt: string;
-}
 /**
  * For each direct child of `treePath` (at the tip of `ref`), find the most
  * recent commit that changed it — the tree view's "last commit" column. Walks
@@ -20,4 +14,4 @@ export declare function getLastCommitsForTree(repo: Repo, options: {
     ref: string;
     treePath?: string;
     depth?: number;
-}, hooks?: OpsHooks): Promise<Record<string, LastCommitInfo>>;
+}, hooks?: OpsHooks): Promise<Record<string, CommitSummary>>;

package/dist/types/ops/submodules.d.ts

@@ -0,0 +1,13 @@
+import type { OpsHooks, Repo } from "./types.js";
+export interface SubmoduleConfig {
+    name: string;
+    path: string;
+    url: string;
+}
+/**
+ * Read only submodule path/url records. Never expands includes, executes Git
+ * commands, or fetches URLs. Ambiguous paths and malformed records are ignored.
+ */
+export declare function parseGitmodules(content: string): SubmoduleConfig[];
+/** The root .gitmodules at this exact revision; absent/oversized config yields no links. */
+export declare function getSubmodules(repo: Repo, ref: string, hooks?: OpsHooks): Promise<SubmoduleConfig[]>;

package/dist/types/ops/tree.d.ts

@@ -2,7 +2,7 @@ import type { Repo } from "./types.js";
 export interface TreeEntry {
     path: string;
     mode: string;
-    type: "blob" | "tree";
+    type: "blob" | "tree" | "commit";
     oid: string;
     size?: number;
 }

package/dist/types/ops/types.d.ts

@@ -14,16 +14,16 @@ export interface Repo {
 }
 /**
  * Key/value store for memoizing expensive walk results (commit logs, tree
- * listings, per-file history). Keys are namespaced `kind:gitdir:headSha:…`,
- * so entries self-invalidate on push (new head, new key) — but evict entries
- * under {@link resultKeyPrefixes} after rewriting a repo's storage out of
- * band, or stale walks leak until your store's own eviction.
+ * listings, per-path history). Keys are namespaced `kind:gitdir:headSha:…`,
+ * so entries self-invalidate on push (new head, new key); evict
+ * {@link resultKeyPrefixes} to drop a repo's superseded entries early.
+ * Values are always objects (arrays or records).
  */
 export interface ResultCache {
-    get<T>(key: string): T | null | undefined;
-    set(key: string, value: unknown): void;
+    get<T extends object>(key: string): T | null | undefined;
+    set(key: string, value: object): void;
 }
-/** Optional instrumentation and tuning hooks accepted by every op. */
+/** Optional instrumentation hooks accepted by every op. */
 export interface OpsHooks {
     resultCache?: ResultCache;
     /** Wrap a timed sub-step (network walk, tree listing). Default: run directly. */
@@ -31,21 +31,15 @@ export interface OpsHooks {
     /** Diagnostic sink for cache hit/miss and walk summaries. */
     onNote?: (message: string) => void;
     /**
-     * Wire pack prefetching (e.g. `GitFs.prefetchPacks`) here so a sequential
-     * walk doesn't pay one network round trip per commit. Called once before
-     * history walks of depth >= `prefetchMinDepth` (see below), and
-     * unconditionally on every cache-miss tree read ({@link getTreeFromRef}) —
-     * a tree read has no shallow case, it always needs at least the head
-     * commit's tree object.
+     * Warm every pack (e.g. `GitFs.prefetchPacks`) before a cache-miss read,
+     * so a sequential walk doesn't discover packs one round trip at a time.
      */
     prefetch?: () => Promise<void>;
-    /** Minimum walk depth before `prefetch` fires for history walks. Default 5. */
-    prefetchMinDepth?: number;
 }
 export declare const runStep: <T>(hooks: OpsHooks | undefined, label: string, fn: () => Promise<T>) => Promise<T>;
 /**
  * The result-cache key prefixes holding entries for `gitdir` — evict these
  * from your {@link ResultCache} when the repo's storage was rewritten outside
- * a normal push (bulk sync, rename, repack cleanup).
+ * a normal push (rename, repack).
  */
 export declare function resultKeyPrefixes(gitdir: string): string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "git-fs-s3",
-  "version": "0.8.0",
-  "description": "isomorphic-git filesystem backend for S3-compatible object storage (AWS S3, Cloudflare R2, MinIO) \u2014 run git servers without a disk",
+  "version": "0.10.0",
+  "description": "isomorphic-git filesystem backend for S3-compatible object storage (AWS S3, Cloudflare R2, MinIO) — run git servers without a disk",
   "type": "module",
   "exports": {
     ".": {