nano-git 0.1.0

package/dist/core/errors.d.mts

@@ -0,0 +1,124 @@
+//#region src/core/errors.d.ts
+/**
+ * nano-git 错误类型体系
+ *
+ * 提供统一的错误类型，便于错误处理和调试。
+ * 所有错误都继承自 GitError 基类。
+ *
+ * 注意：本模块不导入 types.ts，避免循环依赖。
+ */
+/**
+ * Git 错误基类
+ *
+ * 所有 nano-git 抛出的错误都继承自此类。
+ */
+declare class GitError extends Error {
+  constructor(message: string);
+}
+/**
+ * 对象未找到错误
+ *
+ * 当尝试读取不存在的 Git 对象时抛出。
+ */
+declare class ObjectNotFoundError extends GitError {
+  /** 缺失对象的哈希 */
+  hash: string;
+  constructor(hash: string, message?: string);
+}
+/**
+ * 无效的 Git 对象错误
+ *
+ * 当对象格式不符合 Git 规范时抛出。
+ */
+declare class InvalidObjectError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 无效的 SHA-1 哈希错误
+ *
+ * 当字符串不符合 SHA-1 格式（40 个十六进制字符）时抛出。
+ */
+declare class InvalidSHA1Error extends GitError {
+  /** 无效的 SHA-1 字符串 */
+  value: string;
+  constructor(value: string);
+}
+/**
+ * 仓库错误
+ *
+ * 与仓库操作相关的错误。
+ */
+declare class RepositoryError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 循环引用错误
+ *
+ * 当检测到符号引用形成循环时抛出。
+ */
+declare class CircularReferenceError extends GitError {
+  /** 形成循环的引用名称 */
+  ref: string;
+  constructor(ref: string);
+}
+/**
+ * 引用未找到错误
+ *
+ * 当尝试读取不存在的引用时抛出。
+ */
+declare class RefNotFoundError extends GitError {
+  /** 不存在的引用名称 */
+  ref: string;
+  constructor(ref: string);
+}
+/**
+ * Packfile 错误
+ *
+ * 与 Packfile 操作相关的错误。
+ */
+declare class PackError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 无效的 Packfile 错误
+ *
+ * 当 Packfile 格式不符合 Git 规范时抛出。
+ */
+declare class InvalidPackError extends PackError {
+  constructor(message: string);
+}
+/**
+ * Packfile 索引错误
+ *
+ * 当 Packfile 索引（.idx）文件格式不正确时抛出。
+ */
+declare class PackIndexError extends PackError {
+  constructor(message: string);
+}
+/**
+ * Delta 解码错误
+ *
+ * 当 delta 对象解码失败时抛出。
+ */
+declare class DeltaError extends PackError {
+  constructor(message: string);
+}
+/**
+ * 事务错误
+ *
+ * 当事务操作（commit / rollback / write / delete）被非法调用时抛出。
+ */
+declare class TransactionError extends GitError {
+  constructor(message: string);
+}
+/**
+ * 前置条件校验错误
+ *
+ * 当 import session 在 apply() 阶段检测到 preview() 之后
+ * 前置条件（ref 值、期望哈希等）已变化时抛出。
+ */
+declare class PreconditionCheckError extends GitError {
+  constructor(message: string);
+}
+//#endregion
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };

package/dist/core/errors.mjs

@@ -0,0 +1,168 @@
+//#region src/core/errors.ts
+/**
+* nano-git 错误类型体系
+*
+* 提供统一的错误类型，便于错误处理和调试。
+* 所有错误都继承自 GitError 基类。
+*
+* 注意：本模块不导入 types.ts，避免循环依赖。
+*/
+/**
+* Git 错误基类
+*
+* 所有 nano-git 抛出的错误都继承自此类。
+*/
+var GitError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "GitError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/**
+* 对象未找到错误
+*
+* 当尝试读取不存在的 Git 对象时抛出。
+*/
+var ObjectNotFoundError = class extends GitError {
+	/** 缺失对象的哈希 */
+	hash;
+	constructor(hash, message) {
+		super(message ?? `Object not found: ${hash}`);
+		this.name = "ObjectNotFoundError";
+		this.hash = hash;
+	}
+};
+/**
+* 无效的 Git 对象错误
+*
+* 当对象格式不符合 Git 规范时抛出。
+*/
+var InvalidObjectError = class extends GitError {
+	constructor(message) {
+		super(`Invalid Git object: ${message}`);
+		this.name = "InvalidObjectError";
+	}
+};
+/**
+* 无效的 SHA-1 哈希错误
+*
+* 当字符串不符合 SHA-1 格式（40 个十六进制字符）时抛出。
+*/
+var InvalidSHA1Error = class extends GitError {
+	/** 无效的 SHA-1 字符串 */
+	value;
+	constructor(value) {
+		super(`Invalid SHA-1 hash: ${value}`);
+		this.name = "InvalidSHA1Error";
+		this.value = value;
+	}
+};
+/**
+* 仓库错误
+*
+* 与仓库操作相关的错误。
+*/
+var RepositoryError = class extends GitError {
+	constructor(message) {
+		super(message);
+		this.name = "RepositoryError";
+	}
+};
+/**
+* 循环引用错误
+*
+* 当检测到符号引用形成循环时抛出。
+*/
+var CircularReferenceError = class extends GitError {
+	/** 形成循环的引用名称 */
+	ref;
+	constructor(ref) {
+		super(`Circular reference detected: ${ref}`);
+		this.name = "CircularReferenceError";
+		this.ref = ref;
+	}
+};
+/**
+* 引用未找到错误
+*
+* 当尝试读取不存在的引用时抛出。
+*/
+var RefNotFoundError = class extends GitError {
+	/** 不存在的引用名称 */
+	ref;
+	constructor(ref) {
+		super(`Reference not found: ${ref}`);
+		this.name = "RefNotFoundError";
+		this.ref = ref;
+	}
+};
+/**
+* Packfile 错误
+*
+* 与 Packfile 操作相关的错误。
+*/
+var PackError = class extends GitError {
+	constructor(message) {
+		super(`Packfile error: ${message}`);
+		this.name = "PackError";
+	}
+};
+/**
+* 无效的 Packfile 错误
+*
+* 当 Packfile 格式不符合 Git 规范时抛出。
+*/
+var InvalidPackError = class extends PackError {
+	constructor(message) {
+		super(`Invalid packfile: ${message}`);
+		this.name = "InvalidPackError";
+	}
+};
+/**
+* Packfile 索引错误
+*
+* 当 Packfile 索引（.idx）文件格式不正确时抛出。
+*/
+var PackIndexError = class extends PackError {
+	constructor(message) {
+		super(`Pack index error: ${message}`);
+		this.name = "PackIndexError";
+	}
+};
+/**
+* Delta 解码错误
+*
+* 当 delta 对象解码失败时抛出。
+*/
+var DeltaError = class extends PackError {
+	constructor(message) {
+		super(`Delta decode error: ${message}`);
+		this.name = "DeltaError";
+	}
+};
+/**
+* 事务错误
+*
+* 当事务操作（commit / rollback / write / delete）被非法调用时抛出。
+*/
+var TransactionError = class extends GitError {
+	constructor(message) {
+		super(`Transaction error: ${message}`);
+		this.name = "TransactionError";
+	}
+};
+/**
+* 前置条件校验错误
+*
+* 当 import session 在 apply() 阶段检测到 preview() 之后
+* 前置条件（ref 值、期望哈希等）已变化时抛出。
+*/
+var PreconditionCheckError = class extends GitError {
+	constructor(message) {
+		super(message);
+		this.name = "PreconditionCheckError";
+	}
+};
+//#endregion
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };

package/dist/core/hash-digest.d.mts

@@ -0,0 +1,35 @@
+import { ObjectType, SHA1 } from "./types.mjs";
+
+//#region src/core/hash-digest.d.ts
+/**
+ * 计算原始数据的 SHA-1 哈希
+ *
+ * @param data - 原始数据
+ * @returns SHA-1 哈希
+ *
+ * @example
+ * ```ts
+ * const hash = hashData("hello");
+ * console.log(hash);
+ * ```
+ */
+declare function hashData(data: Buffer | string): SHA1;
+/**
+ * 计算 Git 对象的 SHA-1 哈希
+ *
+ * Git 对象的哈希格式: "<type> <size>\0<content>"
+ * 这是 Git 寻址的核心，相同内容总是产生相同的哈希。
+ *
+ * @param type - 对象类型
+ * @param content - 对象内容
+ * @returns 对象哈希
+ *
+ * @example
+ * ```ts
+ * const hash = hashObject("blob", Buffer.from("hello world"));
+ * console.log(hash);
+ * ```
+ */
+declare function hashObject(type: ObjectType, content: Buffer): SHA1;
+//#endregion
+export { hashData, hashObject };

package/dist/core/hash-digest.mjs

@@ -0,0 +1,50 @@
+import { sha1 } from "./types.mjs";
+import { createHash } from "node:crypto";
+//#region src/core/hash-digest.ts
+/**
+* SHA-1 摘要计算
+*
+* 提供原始数据与 Git 对象格式的哈希计算能力。
+*/
+/**
+* 计算原始数据的 SHA-1 哈希
+*
+* @param data - 原始数据
+* @returns SHA-1 哈希
+*
+* @example
+* ```ts
+* const hash = hashData("hello");
+* console.log(hash);
+* ```
+*/
+function hashData(data) {
+	const hash = createHash("sha1");
+	hash.update(data);
+	return sha1(hash.digest("hex"));
+}
+/**
+* 计算 Git 对象的 SHA-1 哈希
+*
+* Git 对象的哈希格式: "<type> <size>\0<content>"
+* 这是 Git 寻址的核心，相同内容总是产生相同的哈希。
+*
+* @param type - 对象类型
+* @param content - 对象内容
+* @returns 对象哈希
+*
+* @example
+* ```ts
+* const hash = hashObject("blob", Buffer.from("hello world"));
+* console.log(hash);
+* ```
+*/
+function hashObject(type, content) {
+	const header = `${type} ${content.length}\0`;
+	const hash = createHash("sha1");
+	hash.update(header);
+	hash.update(content);
+	return sha1(hash.digest("hex"));
+}
+//#endregion
+export { hashData, hashObject };

package/dist/core/hash-file.d.mts

@@ -0,0 +1,20 @@
+import { SHA1 } from "./types.mjs";
+
+//#region src/core/hash-file.d.ts
+/**
+ * 计算文件的 SHA-1 哈希（作为 blob 对象）
+ *
+ * 等价于 `git hash-object <file>`。
+ *
+ * @param filePath - 文件路径
+ * @returns blob 哈希
+ *
+ * @example
+ * ```ts
+ * const hash = hashFile("/tmp/demo.txt");
+ * console.log(hash);
+ * ```
+ */
+declare function hashFile(filePath: string): SHA1;
+//#endregion
+export { hashFile };

package/dist/core/hash-file.mjs

@@ -0,0 +1,27 @@
+import { hashObject } from "./hash-digest.mjs";
+import { readFileSync } from "node:fs";
+//#region src/core/hash-file.ts
+/**
+* 文件哈希入口
+*
+* 提供以 blob 语义计算文件哈希的辅助函数。
+*/
+/**
+* 计算文件的 SHA-1 哈希（作为 blob 对象）
+*
+* 等价于 `git hash-object <file>`。
+*
+* @param filePath - 文件路径
+* @returns blob 哈希
+*
+* @example
+* ```ts
+* const hash = hashFile("/tmp/demo.txt");
+* console.log(hash);
+* ```
+*/
+function hashFile(filePath) {
+	return hashObject("blob", readFileSync(filePath));
+}
+//#endregion
+export { hashFile };

package/dist/core/hash-path.d.mts

@@ -0,0 +1,17 @@
+import { SHA1 } from "./types.mjs";
+
+//#region src/core/hash-path.d.ts
+/**
+ * 验证一个字符串是否是有效的 SHA-1 哈希
+ *
+ * @param value - 待校验字符串
+ * @returns 是否为合法 SHA-1
+ *
+ * @example
+ * ```ts
+ * console.log(isValidSHA1("95d09f2b10159347eece71399a7e2e907ea3df4f"));
+ * ```
+ */
+declare function isValidSHA1(value: string): value is SHA1;
+//#endregion
+export { isValidSHA1 };

package/dist/core/hash-path.mjs

@@ -0,0 +1,35 @@
+//#region src/core/hash-path.ts
+/**
+* 将 SHA-1 哈希转换为对象存储路径
+*
+* Git 将对象存储在 `.git/objects/` 目录下，
+* 前 2 个字符作为目录名，剩余 38 个字符作为文件名。
+*
+* @param hash - 对象哈希
+* @returns 相对对象路径
+*
+* @example
+* ```ts
+* const path = hashToPath(sha1("95d09f2b10159347eece71399a7e2e907ea3df4f"));
+* console.log(path);
+* ```
+*/
+function hashToPath(hash) {
+	return `${hash.slice(0, 2)}/${hash.slice(2)}`;
+}
+/**
+* 验证一个字符串是否是有效的 SHA-1 哈希
+*
+* @param value - 待校验字符串
+* @returns 是否为合法 SHA-1
+*
+* @example
+* ```ts
+* console.log(isValidSHA1("95d09f2b10159347eece71399a7e2e907ea3df4f"));
+* ```
+*/
+function isValidSHA1(value) {
+	return /^[0-9a-f]{40}$/.test(value);
+}
+//#endregion
+export { hashToPath, isValidSHA1 };

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

@@ -0,0 +1,63 @@
+import { RawGitObject, SHA1 } from "../types.mjs";
+
+//#region src/core/types/odb.d.ts
+/**
+ * 只读对象源接口
+ *
+ * 提供 Git 原生原始对象的读取能力。
+ */
+interface ObjectSource {
+  /**
+   * 读取原始对象
+   *
+   * @throws 如果对象不存在
+   */
+  read(hash: SHA1): RawGitObject;
+  /**
+   * 尝试读取原始对象，不存在时返回 undefined
+   *
+   * 相比 `read()` + `catch` 或 `exists()` + `read()` 模式，
+   * `tryRead` 避免了双重查找开销（N+1 问题）。
+   * 默认实现通过 `read()` + catch 回退，各后端可提供优化版本。
+   */
+  tryRead(hash: SHA1): RawGitObject | undefined;
+  /**
+   * 检查对象是否存在
+   */
+  exists(hash: SHA1): boolean;
+  /**
+   * 列出当前对象源中的所有对象哈希
+   */
+  list(): SHA1[];
+}
+/**
+ * 对象数据库接口
+ *
+ * 在 ObjectSource 的基础上增加摄入和删除能力。
+ * 摄入 = 直接写入 canonical raw object，不做语义序列化。
+ */
+interface ObjectDatabase extends ObjectSource {
+  /**
+   * 摄入一个原始对象
+   *
+   * 直接按 canonical raw object 写入存储，不做语义序列化。
+   * 如果对象已存在则幂等跳过。
+   */
+  ingest(raw: RawGitObject): void;
+  /**
+   * 批量摄入原始对象
+   *
+   * 默认实现逐条调用 ingest()，各后端可提供批量优化版本。
+   */
+  ingestMany(objects: Iterable<RawGitObject>): void;
+  /**
+   * 删除指定对象
+   *
+   * 删除不存在的对象应静默成功（no-op）。
+   *
+   * @param hash - 要删除的对象哈希
+   */
+  delete(hash: SHA1): void;
+}
+//#endregion
+export { ObjectDatabase, ObjectSource };

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

@@ -0,0 +1,140 @@
+//#region src/core/types/refs.d.ts
+/**
+ * Refs 存储接口
+ *
+ * 提供 Git 引用的原始读写能力。
+ */
+interface RefStore {
+  /**
+   * 读取引用原始内容
+   *
+   * 返回去掉末尾换行后的引用内容，
+   * 可能包含 "ref: refs/heads/main" 这样的符号引用，
+   * 也可能直接是 SHA-1 哈希值。
+   *
+   * @param ref - 完整引用路径，如 "refs/heads/main"
+   * @returns 引用内容，不存在时返回 null
+   */
+  read(ref: string): string | null;
+  /**
+   * 写入引用
+   *
+   * @param ref - 完整引用路径
+   * @param content - 引用内容（末尾换行会被自动规范化）
+   */
+  write(ref: string, content: string): void;
+  /**
+   * 删除引用
+   *
+   * @param ref - 完整引用路径
+   * @throws 如果引用不存在
+   */
+  delete(ref: string): void;
+  /**
+   * 列出指定前缀下的所有引用
+   *
+   * @param prefix - 引用前缀，如 "refs/heads/"
+   * @returns 完整的引用路径列表（已排序）
+   */
+  list(prefix: string): string[];
+  /**
+   * 列出所有引用（不限命名空间）
+   *
+   * 返回 refs/ 下的所有引用完整路径。
+   * 此方法不做前缀校验，适用于需要扫描全部 refs 的场景。
+   *
+   * @returns 所有引用的完整路径列表（已排序）
+   */
+  listAll(): string[];
+  /**
+   * 开启一个新的事务
+   *
+   * 事务中所有变更独立于事务外操作。
+   * 未提交的事务在调用 rollback() 或 GC 时丢弃。
+   *
+   * @param hooks - 可选的事务生命周期钩子
+   */
+  beginTransaction(hooks?: RefTransactionHook[]): RefTransaction;
+}
+/**
+ * Reference Transaction
+ *
+ * 提供批量 ref 更新的原子性语义。
+ * 所有变更暂存于内部缓冲区，commit() 时一次性应用。
+ */
+interface RefTransaction {
+  /** 当前事务中暂存的变更数（write + delete） */
+  readonly pendingCount: number;
+  /**
+   * 暂存写入操作
+   *
+   * 不会立即写入存储，只记录 pending 变更。
+   * 事务内对同一 ref 多次 write 以最后一次为准。
+   */
+  write(ref: string, content: string): void;
+  /**
+   * 暂存删除操作
+   *
+   * 不会立即删除，只记录 pending 变更。
+   * write + delete 同一 ref 以最后一次操作为准。
+   */
+  delete(ref: string): void;
+  /**
+   * 提交事务，原子性应用所有变更
+   *
+   * 提交顺序：先 apply 所有 write，再 apply 所有 delete。
+   * 失败时整体回滚，不留下部分变更。
+   *
+   * @throws 如果任意写入失败，事务自动回滚并抛出异常
+   */
+  commit(): void;
+  /**
+   * 回滚事务，丢弃所有 pending 变更
+   *
+   * 恢复至 beginTransaction() 时的状态。
+   * 多次调用或 commit 后调用无副作用。
+   */
+  rollback(): void;
+}
+/**
+ * 事务的只读快照，用于 Hook 回调
+ */
+interface ReadonlyRefTransaction {
+  readonly pendingCount: number;
+  readonly writes: ReadonlyArray<{
+    readonly ref: string;
+    readonly content: string;
+  }>;
+  readonly deletes: ReadonlyArray<{
+    readonly ref: string;
+  }>;
+}
+/**
+ * Reference Transaction Hook
+ *
+ * 类似 Git reference-transaction hook，
+ * 在事务生命周期三个阶段触发回调。
+ */
+interface RefTransactionHook {
+  /**
+   * 提交前准备阶段
+   *
+   * commit() 进行实际写入前调用。
+   * 抛异常可中止本次提交，事务自动回滚。
+   */
+  onPrepare?(tx: ReadonlyRefTransaction): void;
+  /**
+   * 提交成功
+   *
+   * 所有变更已持久化后调用。
+   */
+  onCommitted?(tx: ReadonlyRefTransaction): void;
+  /**
+   * 提交中止
+   *
+   * 事务被回滚后调用（含显式 rollback() 和 commit() 内失败自动回滚）。
+   */
+  onAborted?(tx: ReadonlyRefTransaction): void;
+}
+//#endregion
+export { RefStore, RefTransactionHook };

package/dist/core/types/refs.mjs

@@ -0,0 +1,19 @@
+//#region src/core/types/refs.ts
+/**
+* Refs 存储接口定义
+*
+* 提供 Git 引用（refs）的持久化存储能力。
+* 所有存储实现（文件系统、内存等）都遵循此接口。
+*
+* 此接口只做原始读写，不包含符号引用解析逻辑（解析逻辑在 utils.ts 中）。
+*
+* 扩展点：添加新存储后端时，只需实现此接口即可无缝集成。
+*/
+/** HEAD 引用名称 */
+const HEAD_REF = "HEAD";
+/** 分支引用前缀 */
+const HEADS_PREFIX = "refs/heads/";
+/** 标签引用前缀 */
+const TAGS_PREFIX = "refs/tags/";
+//#endregion
+export { HEADS_PREFIX, HEAD_REF, TAGS_PREFIX };