nano-git 0.1.0

package/dist/core/types/shallow.d.mts

@@ -0,0 +1,52 @@
+import { SHA1 } from "../types.mjs";
+
+//#region src/core/types/shallow.d.ts
+/**
+ * Shallow 边界更新
+ *
+ * 表示一次 fetch 操作中 shallow 边界集合的增减变化。
+ */
+interface ShallowUpdate {
+  /** 新增的 shallow 边界 commit 哈希列表 */
+  readonly shallow: SHA1[];
+  /** 从 shallow 边界移除的 commit 哈希列表（变为完整） */
+  readonly unshallow: SHA1[];
+}
+/**
+ * Shallow 存储接口
+ *
+ * 提供 Git shallow 边界集合的读写能力。
+ */
+interface ShallowStore {
+  /**
+   * 读取当前 shallow 边界集合
+   *
+   * 返回当前仓库标记为 shallow 边界（即只拉取了部分历史）的 commit 哈希列表。
+   * 非 shallow 仓库返回空数组。
+   * 返回值为排序后的新数组副本，修改不影响内部状态。
+   */
+  read(): SHA1[];
+  /**
+   * 完全替换 shallow 边界集合
+   *
+   * 将 shallow 边界集合替换为给定列表。
+   * 传空数组表示移除此仓库的 shallow 状态（转为完整仓库）。
+   */
+  write(boundaries: SHA1[]): void;
+  /**
+   * 增量更新 shallow 边界
+   *
+   * 根据 fetch 操作返回的 shallow/unshallow 信息，做集合变换：
+   * - 加入 server 新返回的 shallow 边界
+   * - 删除 server 返回的 unshallow 边界
+   */
+  applyUpdate(update: ShallowUpdate): void;
+  /**
+   * 判断指定哈希是否为 shallow boundary commit
+   *
+   * 若哈希在当前 shallow 边界集合中返回 true，否则返回 false。
+   */
+  isShallow(hash: SHA1): boolean;
+}
+//#endregion
+export { ShallowStore };

package/dist/core/types.d.mts

@@ -0,0 +1,154 @@
+//#region src/core/types.d.ts
+/**
+ * nano-git 核心类型定义
+ *
+ * Git 的对象模型：
+ * - 所有对象通过 SHA-1 哈希寻址（40 个十六进制字符）
+ * - 四种对象类型：blob, tree, commit, tag
+ * - 对象以 "<type> <size>\0<content>" 格式存储
+ */
+/** SHA-1 哈希值（40 个十六进制字符） */
+type SHA1 = string & {
+  readonly __brand: "SHA1";
+};
+/** Git 对象类型 */
+type ObjectType = "blob" | "tree" | "commit" | "tag";
+/**
+ * 底层原始 Git 对象（ODB 的真实边界）
+ *
+ * 直接对应 Git 存储格式中的 "<type> <size>\0<content>"，
+ * ODB 的 read/ingest 操作均以此为单元，不再直接操作 GitObject。
+ *
+ * @see GitObject - 语义层 AST，供查看、遍历、构造新对象使用
+ */
+interface RawGitObject {
+  /** SHA-1 哈希（由 type + content 计算得出） */
+  readonly hash: SHA1;
+  /** 对象类型 */
+  readonly type: ObjectType;
+  /** 去 header 后的原始内容 */
+  readonly content: Buffer;
+}
+/**
+ * 验证并转换字符串为 ObjectType
+ *
+ * @throws InvalidObjectError 如果字符串不是合法的 ObjectType
+ *
+ * @example
+ * ```ts
+ * assertObjectType("blob"); // => "blob"
+ * assertObjectType("invalid"); // throws InvalidObjectError
+ * ```
+ */
+declare function assertObjectType(value: string): ObjectType;
+/** Blob 对象 — 存储文件内容 */
+interface GitBlob {
+  type: "blob";
+  content: Buffer;
+}
+/** Tree 条目 — 目录中的一个文件或子目录 */
+interface TreeEntry {
+  /** 文件模式（如 "100644" 普通文件, "100755" 可执行文件, "40000" 目录） */
+  mode: string;
+  /** 文件/目录名 */
+  name: string;
+  /** 指向的 SHA-1 哈希 */
+  hash: SHA1;
+}
+/** Tree 对象 — 存储目录结构 */
+interface GitTree {
+  type: "tree";
+  entries: TreeEntry[];
+}
+/** Commit 自定义 header */
+interface GitCommitExtraHeader {
+  /**
+   * Header 名称
+   *
+   * 不能与内建字段重名。
+   */
+  name: string;
+  /** Header 值（多行 header 使用 `\n` 表示续行） */
+  value: string;
+}
+/** Commit 对象 — 存储快照信息 */
+interface GitCommit {
+  type: "commit";
+  /** 指向的 tree 对象哈希 */
+  tree: SHA1;
+  /** 父 commit 哈希列表（merge commit 有多个父节点） */
+  parents: SHA1[];
+  /** 作者信息 */
+  author: GitAuthor;
+  /** 提交者信息 */
+  committer: GitAuthor;
+  /** 可选字符编码声明 */
+  encoding?: string;
+  /** GPG 签名块（不含 continuation 行前导空格） */
+  gpgsig?: string;
+  /** merge tag 块列表（不含 continuation 行前导空格） */
+  mergetag?: string[];
+  /**
+   * 自定义 header 列表
+   *
+   * 序列化时会按数组顺序输出在内建 header 之后。
+   */
+  extraHeaders?: GitCommitExtraHeader[];
+  /** 提交信息 */
+  message: string;
+}
+/** 作者/提交者信息 */
+interface GitAuthor {
+  name: string;
+  email: string;
+  /** Unix 时间戳（秒） */
+  timestamp: number;
+  /** 时区偏移（如 "+0800"） */
+  timezone: string;
+}
+/** Tag 对象 — 带注释的标签 */
+interface GitTag {
+  type: "tag";
+  /** 指向的对象哈希 */
+  object: SHA1;
+  /** 被标记对象的类型 */
+  objectType: ObjectType;
+  /** 标签名 */
+  tag: string;
+  /** 标签创建者 */
+  tagger: GitAuthor;
+  /** GPG 签名块（不含 continuation 行前导空格） */
+  gpgsig?: string;
+  /**
+   * 自定义 header 列表
+   *
+   * 序列化时会按数组顺序输出在内建 header 之后。
+   */
+  extraHeaders?: GitCommitExtraHeader[];
+  /** 标签信息 */
+  message: string;
+}
+/**
+ * 所有 Git 对象的联合类型（语义层 AST）
+ *
+ * 用于查看、遍历和构造新对象。不直接作为 ODB 的存储边界。
+ * ODB 的真实边界是 RawGitObject。
+ *
+ * @see RawGitObject - ODB 层使用的底层原始对象
+ */
+type GitObject = GitBlob | GitTree | GitCommit | GitTag;
+/**
+ * 创建 SHA1 类型的辅助函数
+ *
+ * @param value - 待校验的哈希字符串
+ * @returns 带品牌的 SHA1 字符串
+ *
+ * @example
+ * ```ts
+ * const hash = sha1("95d09f2b10159347eece71399a7e2e907ea3df4f");
+ * console.log(hash);
+ * ```
+ */
+declare function sha1(value: string): SHA1;
+//#endregion
+export { GitAuthor, GitBlob, GitCommit, GitCommitExtraHeader, GitObject, GitTag, GitTree, ObjectType, RawGitObject, SHA1, TreeEntry, assertObjectType, sha1 };

package/dist/core/types.mjs

@@ -0,0 +1,43 @@
+import { InvalidObjectError, InvalidSHA1Error } from "./errors.mjs";
+//#region src/core/types.ts
+/**
+* nano-git 核心类型定义
+*
+* Git 的对象模型：
+* - 所有对象通过 SHA-1 哈希寻址（40 个十六进制字符）
+* - 四种对象类型：blob, tree, commit, tag
+* - 对象以 "<type> <size>\0<content>" 格式存储
+*/
+/**
+* 验证并转换字符串为 ObjectType
+*
+* @throws InvalidObjectError 如果字符串不是合法的 ObjectType
+*
+* @example
+* ```ts
+* assertObjectType("blob"); // => "blob"
+* assertObjectType("invalid"); // throws InvalidObjectError
+* ```
+*/
+function assertObjectType(value) {
+	if (value === "blob" || value === "tree" || value === "commit" || value === "tag") return value;
+	throw new InvalidObjectError(`unknown object type: ${value}`);
+}
+/**
+* 创建 SHA1 类型的辅助函数
+*
+* @param value - 待校验的哈希字符串
+* @returns 带品牌的 SHA1 字符串
+*
+* @example
+* ```ts
+* const hash = sha1("95d09f2b10159347eece71399a7e2e907ea3df4f");
+* console.log(hash);
+* ```
+*/
+function sha1(value) {
+	if (!/^[0-9a-f]{40}$/.test(value)) throw new InvalidSHA1Error(value);
+	return value;
+}
+//#endregion
+export { assertObjectType, sha1 };

package/dist/errors.d.mts

@@ -0,0 +1,2 @@
+import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError } from "./core/errors.mjs";
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };

package/dist/errors.mjs

@@ -0,0 +1,2 @@
+import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError } from "./core/errors.mjs";
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };

package/dist/hash-file.d.mts

@@ -0,0 +1,2 @@
+import { hashFile } from "./core/hash-file.mjs";
+export { hashFile };

package/dist/hash-file.mjs

@@ -0,0 +1,2 @@
+import { hashFile } from "./core/hash-file.mjs";
+export { hashFile };

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import { GitAuthor, GitBlob, GitCommit, GitCommitExtraHeader, GitObject, GitTag, GitTree, ObjectType, RawGitObject, SHA1, TreeEntry, assertObjectType, sha1 } from "./core/types.mjs";
+import { PackRepackOptions, RepositoryBackend, RepositoryGCOptions, RepositoryPackSupport, RepositoryRepackOptions } from "./backend/types.mjs";
+import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError } from "./core/errors.mjs";
+import { FileRepository, Repository } from "./repository/types.mjs";
+import { hashData, hashObject } from "./core/hash-digest.mjs";
+import { isValidSHA1 } from "./core/hash-path.mjs";
+import { deserializeBlob, serializeBlob } from "./objects/blob.mjs";
+import { deserializeTree, serializeTree } from "./objects/tree.mjs";
+import { deserializeCommit, serializeCommit } from "./objects/commit.mjs";
+import { deserializeTag, serializeTag } from "./objects/tag.mjs";
+import { formatAuthor, parseAuthor } from "./objects/author.mjs";
+import { deserialize, deserializeContent, serialize, serializeContent } from "./objects/codec.mjs";
+import { decodeObject, encodeObject, readObject, tryReadObject, writeObject } from "./objects/raw.mjs";
+import { branchNameToRef, normalizeShortRefName, tagNameToRef, validateRefName, validateRefPrefix } from "./refs/names.mjs";
+import { resolveRefHash, resolveSymbolicRef, resolveTargetHash } from "./refs/resolve.mjs";
+export { CircularReferenceError, DeltaError, type FileRepository, type GitAuthor, type GitBlob, type GitCommit, type GitCommitExtraHeader, GitError, type GitObject, type GitTag, type GitTree, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, type ObjectType, PackError, PackIndexError, type PackRepackOptions, PreconditionCheckError, type RawGitObject, RefNotFoundError, type Repository, type RepositoryBackend, RepositoryError, type RepositoryGCOptions, type RepositoryPackSupport, type RepositoryRepackOptions, type SHA1, TransactionError, type TreeEntry, assertObjectType, branchNameToRef, decodeObject, deserialize, deserializeBlob, deserializeCommit, deserializeContent, deserializeTag, deserializeTree, encodeObject, formatAuthor, hashData, hashObject, isValidSHA1, normalizeShortRefName, parseAuthor, readObject, resolveRefHash, resolveSymbolicRef, resolveTargetHash, serialize, serializeBlob, serializeCommit, serializeContent, serializeTag, serializeTree, sha1, tagNameToRef, tryReadObject, validateRefName, validateRefPrefix, writeObject };

package/dist/index.mjs

@@ -0,0 +1,14 @@
+import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError } from "./core/errors.mjs";
+import { assertObjectType, sha1 } from "./core/types.mjs";
+import { hashData, hashObject } from "./core/hash-digest.mjs";
+import { isValidSHA1 } from "./core/hash-path.mjs";
+import { deserializeBlob, serializeBlob } from "./objects/blob.mjs";
+import { deserializeTree, serializeTree } from "./objects/tree.mjs";
+import { formatAuthor, parseAuthor } from "./objects/author.mjs";
+import { deserializeCommit, serializeCommit } from "./objects/commit.mjs";
+import { deserializeTag, serializeTag } from "./objects/tag.mjs";
+import { deserialize, deserializeContent, serialize, serializeContent } from "./objects/codec.mjs";
+import { decodeObject, encodeObject, readObject, tryReadObject, writeObject } from "./objects/raw.mjs";
+import { branchNameToRef, normalizeShortRefName, tagNameToRef, validateRefName, validateRefPrefix } from "./refs/names.mjs";
+import { resolveRefHash, resolveSymbolicRef, resolveTargetHash } from "./refs/resolve.mjs";
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError, assertObjectType, branchNameToRef, decodeObject, deserialize, deserializeBlob, deserializeCommit, deserializeContent, deserializeTag, deserializeTree, encodeObject, formatAuthor, hashData, hashObject, isValidSHA1, normalizeShortRefName, parseAuthor, readObject, resolveRefHash, resolveSymbolicRef, resolveTargetHash, serialize, serializeBlob, serializeCommit, serializeContent, serializeTag, serializeTree, sha1, tagNameToRef, tryReadObject, validateRefName, validateRefPrefix, writeObject };

package/dist/objects/author.d.mts

@@ -0,0 +1,25 @@
+import { GitAuthor } from "../core/types.mjs";
+
+//#region src/objects/author.d.ts
+/**
+ * 格式化作者信息为 Git 标准格式
+ *
+ * @example
+ * ```ts
+ * formatAuthor({ name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" })
+ * // => "John <j@e.com> 123 +0800"
+ * ```
+ */
+declare function formatAuthor(author: GitAuthor): string;
+/**
+ * 解析 Git 标准格式的作者信息
+ *
+ * @example
+ * ```ts
+ * parseAuthor("John <j@e.com> 123 +0800")
+ * // => { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" }
+ * ```
+ */
+declare function parseAuthor(text: string): GitAuthor;
+//#endregion
+export { formatAuthor, parseAuthor };

package/dist/objects/author.mjs

@@ -0,0 +1,45 @@
+import { InvalidObjectError } from "../core/errors.mjs";
+//#region src/objects/author.ts
+/**
+* 作者信息格式化与解析
+*
+* Git 中作者信息的格式:
+*   "<name> <<email>> <timestamp> <timezone>"
+*
+* 例如: "John Doe <john@example.com> 1234567890 +0800"
+*
+* 此格式在 commit 和 tag 对象中共享使用。
+*/
+/**
+* 格式化作者信息为 Git 标准格式
+*
+* @example
+* ```ts
+* formatAuthor({ name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" })
+* // => "John <j@e.com> 123 +0800"
+* ```
+*/
+function formatAuthor(author) {
+	return `${author.name} <${author.email}> ${author.timestamp} ${author.timezone}`;
+}
+/**
+* 解析 Git 标准格式的作者信息
+*
+* @example
+* ```ts
+* parseAuthor("John <j@e.com> 123 +0800")
+* // => { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" }
+* ```
+*/
+function parseAuthor(text) {
+	const match = text.match(/^(.+?) <(.+?)> (\d+) ([+-]\d{4})$/);
+	if (!match) throw new InvalidObjectError(`invalid author format: ${text}`);
+	return {
+		name: match[1],
+		email: match[2],
+		timestamp: parseInt(match[3], 10),
+		timezone: match[4]
+	};
+}
+//#endregion
+export { formatAuthor, parseAuthor };

package/dist/objects/blob.d.mts

@@ -0,0 +1,15 @@
+import { GitBlob } from "../core/types.mjs";
+
+//#region src/objects/blob.d.ts
+/**
+ * 序列化 Blob 对象
+ *
+ * Blob 的内容就是原始文件数据，无需额外处理。
+ */
+declare function serializeBlob(blob: GitBlob): Buffer;
+/**
+ * 反序列化 Blob 对象
+ */
+declare function deserializeBlob(content: Buffer): GitBlob;
+//#endregion
+export { deserializeBlob, serializeBlob };

package/dist/objects/blob.mjs

@@ -0,0 +1,20 @@
+//#region src/objects/blob.ts
+/**
+* 序列化 Blob 对象
+*
+* Blob 的内容就是原始文件数据，无需额外处理。
+*/
+function serializeBlob(blob) {
+	return blob.content;
+}
+/**
+* 反序列化 Blob 对象
+*/
+function deserializeBlob(content) {
+	return {
+		type: "blob",
+		content
+	};
+}
+//#endregion
+export { deserializeBlob, serializeBlob };

package/dist/objects/codec.d.mts

@@ -0,0 +1,46 @@
+import { GitObject, ObjectType } from "../core/types.mjs";
+
+//#region src/objects/codec.d.ts
+/**
+ * 序列化 Git 对象为完整的存储格式
+ *
+ * @example
+ * ```ts
+ * const blob: GitBlob = { type: "blob", content: Buffer.from("hello") };
+ * const data = serialize(blob);
+ * // => Buffer("blob 5\0hello")
+ * ```
+ */
+declare function serialize(obj: GitObject): Buffer;
+/**
+ * 反序列化完整的存储格式为 Git 对象
+ *
+ * @example
+ * ```ts
+ * const obj = deserialize(Buffer.from("blob 5\0hello"));
+ * console.log(obj.type); // => "blob"
+ * ```
+ */
+declare function deserialize(data: Buffer): GitObject;
+/**
+ * 序列化对象内容（不含 header）
+ *
+ * @example
+ * ```ts
+ * const content = serializeContent({ type: "blob", content: Buffer.from("hello") });
+ * console.log(content.toString("utf-8")); // => "hello"
+ * ```
+ */
+declare function serializeContent(obj: GitObject): Buffer;
+/**
+ * 反序列化对象内容（不含 header）
+ *
+ * @example
+ * ```ts
+ * const obj = deserializeContent("blob", Buffer.from("hello"));
+ * console.log(obj.type); // => "blob"
+ * ```
+ */
+declare function deserializeContent(type: ObjectType, content: Buffer): GitObject;
+//#endregion
+export { deserialize, deserializeContent, serialize, serializeContent };

package/dist/objects/codec.mjs

@@ -0,0 +1,84 @@
+import { InvalidObjectError } from "../core/errors.mjs";
+import { assertObjectType } from "../core/types.mjs";
+import { deserializeBlob, serializeBlob } from "./blob.mjs";
+import { deserializeTree, serializeTree } from "./tree.mjs";
+import { deserializeCommit, serializeCommit } from "./commit.mjs";
+import { deserializeTag, serializeTag } from "./tag.mjs";
+//#region src/objects/codec.ts
+/**
+* Git 对象编解码
+*
+* 提供完整对象格式与对象内容格式之间的转换能力。
+*/
+/**
+* 序列化 Git 对象为完整的存储格式
+*
+* @example
+* ```ts
+* const blob: GitBlob = { type: "blob", content: Buffer.from("hello") };
+* const data = serialize(blob);
+* // => Buffer("blob 5\0hello")
+* ```
+*/
+function serialize(obj) {
+	const content = serializeContent(obj);
+	const header = `${obj.type} ${content.length}\0`;
+	return Buffer.concat([Buffer.from(header), content]);
+}
+/**
+* 反序列化完整的存储格式为 Git 对象
+*
+* @example
+* ```ts
+* const obj = deserialize(Buffer.from("blob 5\0hello"));
+* console.log(obj.type); // => "blob"
+* ```
+*/
+function deserialize(data) {
+	const nullIndex = data.indexOf(0);
+	if (nullIndex === -1) throw new InvalidObjectError("missing null byte");
+	const header = data.subarray(0, nullIndex).toString("utf-8");
+	const match = header.match(/^(blob|tree|commit|tag) (\d+)$/);
+	if (!match) throw new InvalidObjectError(`invalid header: ${header}`);
+	const type = assertObjectType(match[1]);
+	const size = parseInt(match[2], 10);
+	const content = data.subarray(nullIndex + 1);
+	if (content.length !== size) throw new InvalidObjectError(`size mismatch: header says ${size}, got ${content.length}`);
+	return deserializeContent(type, content);
+}
+/**
+* 序列化对象内容（不含 header）
+*
+* @example
+* ```ts
+* const content = serializeContent({ type: "blob", content: Buffer.from("hello") });
+* console.log(content.toString("utf-8")); // => "hello"
+* ```
+*/
+function serializeContent(obj) {
+	switch (obj.type) {
+		case "blob": return serializeBlob(obj);
+		case "tree": return serializeTree(obj);
+		case "commit": return serializeCommit(obj);
+		case "tag": return serializeTag(obj);
+	}
+}
+/**
+* 反序列化对象内容（不含 header）
+*
+* @example
+* ```ts
+* const obj = deserializeContent("blob", Buffer.from("hello"));
+* console.log(obj.type); // => "blob"
+* ```
+*/
+function deserializeContent(type, content) {
+	switch (type) {
+		case "blob": return deserializeBlob(content);
+		case "tree": return deserializeTree(content);
+		case "commit": return deserializeCommit(content);
+		case "tag": return deserializeTag(content);
+	}
+}
+//#endregion
+export { deserialize, deserializeContent, serialize, serializeContent };

package/dist/objects/commit.d.mts

@@ -0,0 +1,26 @@
+import { GitCommit } from "../core/types.mjs";
+
+//#region src/objects/commit.d.ts
+/**
+ * 序列化 Commit 对象
+ *
+ * @example
+ * ```ts
+ * const commit: GitCommit = {
+ *   type: "commit",
+ *   tree: sha1("abc..."),
+ *   parents: [],
+ *   author: { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" },
+ *   committer: { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" },
+ *   message: "Initial commit",
+ * };
+ * const buf = serializeCommit(commit);
+ * ```
+ */
+declare function serializeCommit(commit: GitCommit): Buffer;
+/**
+ * 反序列化 Commit 对象
+ */
+declare function deserializeCommit(content: Buffer): GitCommit;
+//#endregion
+export { deserializeCommit, serializeCommit };