nano-git 0.1.0

package/dist/pack/delta-create.d.mts

@@ -0,0 +1,28 @@
+//#region src/pack/delta-create.d.ts
+/**
+ * Delta 创建（编码）
+ *
+ * 使用哈希表（Rabin-Karp 风格）加速模式匹配：
+ * - 预处理 base 中所有 4 字节窗口，构建哈希索引
+ * - 对 target 的每个位置，通过哈希表 O(1) 定位候选匹配
+ * - 平均时间复杂度 O(B+T)，最坏 O(B×T×K)（K 为每桶候选数上限）
+ */
+/**
+ * 创建 delta 数据（从 base object 到 target object 的差异）
+ *
+ * 使用哈希表加速贪心匹配策略，相比暴力扫描大幅减少匹配搜索开销。
+ *
+ * @param base - base object 的原始数据
+ * @param target - 目标对象的原始数据
+ * @returns delta 数据
+ *
+ * @example
+ * ```ts
+ * const base = Buffer.from("hello world");
+ * const target = Buffer.from("hello git");
+ * const delta = createDelta(base, target);
+ * ```
+ */
+declare function createDelta(base: Buffer, target: Buffer): Buffer;
+//#endregion
+export { createDelta };

package/dist/pack/delta-create.mjs

@@ -0,0 +1,151 @@
+import { encodeVarint } from "./varint.mjs";
+//#region src/pack/delta-create.ts
+/**
+* Delta 创建（编码）
+*
+* 使用哈希表（Rabin-Karp 风格）加速模式匹配：
+* - 预处理 base 中所有 4 字节窗口，构建哈希索引
+* - 对 target 的每个位置，通过哈希表 O(1) 定位候选匹配
+* - 平均时间复杂度 O(B+T)，最坏 O(B×T×K)（K 为每桶候选数上限）
+*/
+/**
+* 创建 delta 数据（从 base object 到 target object 的差异）
+*
+* 使用哈希表加速贪心匹配策略，相比暴力扫描大幅减少匹配搜索开销。
+*
+* @param base - base object 的原始数据
+* @param target - 目标对象的原始数据
+* @returns delta 数据
+*
+* @example
+* ```ts
+* const base = Buffer.from("hello world");
+* const target = Buffer.from("hello git");
+* const delta = createDelta(base, target);
+* ```
+*/
+function createDelta(base, target) {
+	const parts = [];
+	parts.push(encodeVarint(base.length));
+	parts.push(encodeVarint(target.length));
+	const hashTable = buildHashTable(base);
+	let targetOffset = 0;
+	while (targetOffset < target.length) {
+		const match = findBestMatch(base, target, targetOffset, hashTable);
+		if (match && match.length >= 4) {
+			parts.push(encodeCopyInstruction(match.offset, match.length));
+			targetOffset += match.length;
+			continue;
+		}
+		let insertEnd = targetOffset + 1;
+		while (insertEnd < target.length) {
+			const nextMatch = findBestMatch(base, target, insertEnd, hashTable);
+			if (nextMatch && nextMatch.length >= 4) break;
+			insertEnd++;
+			if (insertEnd - targetOffset >= 127) break;
+		}
+		const insertSize = insertEnd - targetOffset;
+		parts.push(Buffer.from([insertSize]));
+		parts.push(target.subarray(targetOffset, insertEnd));
+		targetOffset = insertEnd;
+	}
+	return Buffer.concat(parts);
+}
+/** 每个哈希值保留的最大候选位置数（防止重复字符串退化） */
+const MAX_CANDIDATES_PER_HASH = 32;
+/**
+* 构建 4 字节窗口哈希表
+*
+* 将 base 中每个 4 字节子串的精确值作为哈希键，
+* 映射到出现该子串的偏移量列表。
+*/
+function buildHashTable(base) {
+	const table = /* @__PURE__ */ new Map();
+	for (let i = 0; i <= base.length - 4; i++) {
+		const hash = hash4(base, i);
+		let positions = table.get(hash);
+		if (!positions) {
+			positions = [];
+			table.set(hash, positions);
+		}
+		if (positions.length < MAX_CANDIDATES_PER_HASH) positions.push(i);
+	}
+	return table;
+}
+/**
+* 计算 Buffer 中 4 字节窗口的 32 位哈希值
+*
+* 使用精确的 4 字节值（大端序）作为哈希，保证相同 4 字节序列得到相同值。
+*/
+function hash4(buf, offset) {
+	return (buf[offset] << 24 | buf[offset + 1] << 16 | buf[offset + 2] << 8 | buf[offset + 3]) >>> 0;
+}
+/**
+* 使用哈希表查找与 target[targetOffset] 开始的最长匹配
+*
+* 只在哈希表中存在对应 4 字节前缀的位置上搜索匹配并扩展，
+* 替代原实现的暴力全量扫描。
+*
+* @param hashTable - buildHashTable 构建的哈希表
+*/
+function findBestMatch(base, target, targetOffset, hashTable) {
+	if (targetOffset + 4 > target.length) return null;
+	const targetHash = hash4(target, targetOffset);
+	const candidates = hashTable.get(targetHash);
+	if (!candidates || candidates.length === 0) return null;
+	let bestMatch = null;
+	const maxLen = Math.min(target.length - targetOffset, 65535);
+	for (const baseOffset of candidates) {
+		let len = 4;
+		while (len < maxLen && baseOffset + len < base.length && base[baseOffset + len] === target[targetOffset + len]) len++;
+		if (len > (bestMatch?.length ?? 0)) {
+			bestMatch = {
+				offset: baseOffset,
+				length: len
+			};
+			if (len === maxLen) break;
+		}
+	}
+	return bestMatch;
+}
+function encodeCopyInstruction(offset, size) {
+	const bytes = [];
+	let cmd = 128;
+	const offsetBytes = [];
+	if (offset & 255) {
+		cmd |= 1;
+		offsetBytes.push(offset & 255);
+	}
+	if (offset & 65280) {
+		cmd |= 2;
+		offsetBytes.push(offset >> 8 & 255);
+	}
+	if (offset & 16711680) {
+		cmd |= 4;
+		offsetBytes.push(offset >> 16 & 255);
+	}
+	if (offset & 4278190080) {
+		cmd |= 8;
+		offsetBytes.push(offset >> 24 & 255);
+	}
+	const sizeBytes = [];
+	if (size !== 65536) {
+		if (size & 255) {
+			cmd |= 16;
+			sizeBytes.push(size & 255);
+		}
+		if (size & 65280) {
+			cmd |= 32;
+			sizeBytes.push(size >> 8 & 255);
+		}
+		if (size & 16711680) {
+			cmd |= 64;
+			sizeBytes.push(size >> 16 & 255);
+		}
+	}
+	bytes.push(cmd);
+	bytes.push(...offsetBytes, ...sizeBytes);
+	return Buffer.from(bytes);
+}
+//#endregion
+export { createDelta };

package/dist/pack/index.d.mts

@@ -0,0 +1,16 @@
+import { PackBuildResult } from "./pack-builder-types.mjs";
+import { PackBuilder, createPackBuilder } from "./pack-builder.mjs";
+import { PackObject, packObjectToRaw } from "./pack-reader-types.mjs";
+import { createPackReader } from "./pack-reader.mjs";
+import { PackIndexEntry } from "./pack-index-types.mjs";
+import { PackIndexReader, createPackIndexReader } from "./pack-index-reader.mjs";
+import { PackIndexWriter, createPackIndexWriter } from "./pack-index-writer.mjs";
+import { PackFileInfo } from "./pack-store-types.mjs";
+import { PackObjectStore, createPackObjectStore } from "./pack-store.mjs";
+import { CompositeObjectDatabase, createCompositeObjectDatabase } from "./composite-store.mjs";
+import { applyDelta } from "./delta-apply.mjs";
+import { createDelta } from "./delta-create.mjs";
+import { decodeObjectHeader, encodeObjectHeader } from "./object-header.mjs";
+import { decodeOfsDeltaOffset, encodeOfsDeltaOffset } from "./ofs-delta-offset.mjs";
+import { decodeVarint, encodeVarint } from "./varint.mjs";
+export { CompositeObjectDatabase, type PackBuildResult, type PackBuilder, type PackFileInfo, type PackIndexEntry, type PackIndexReader, type PackIndexWriter, type PackObject, type PackObjectStore, applyDelta, createCompositeObjectDatabase, createDelta, createPackBuilder, createPackIndexReader, createPackIndexWriter, createPackObjectStore, createPackReader, decodeObjectHeader, decodeOfsDeltaOffset, decodeVarint, encodeObjectHeader, encodeOfsDeltaOffset, encodeVarint, packObjectToRaw };

package/dist/pack/index.mjs

@@ -0,0 +1,13 @@
+import { decodeObjectHeader, encodeObjectHeader } from "./object-header.mjs";
+import { decodeOfsDeltaOffset, encodeOfsDeltaOffset } from "./ofs-delta-offset.mjs";
+import { decodeVarint, encodeVarint } from "./varint.mjs";
+import { applyDelta } from "./delta-apply.mjs";
+import { createDelta } from "./delta-create.mjs";
+import { packObjectToRaw } from "./pack-reader-types.mjs";
+import { createPackReader } from "./pack-reader.mjs";
+import { createPackIndexReader } from "./pack-index-reader.mjs";
+import { createPackIndexWriter } from "./pack-index-writer.mjs";
+import { createPackBuilder } from "./pack-builder.mjs";
+import { createPackObjectStore } from "./pack-store.mjs";
+import { CompositeObjectDatabase, createCompositeObjectDatabase } from "./composite-store.mjs";
+export { CompositeObjectDatabase, applyDelta, createCompositeObjectDatabase, createDelta, createPackBuilder, createPackIndexReader, createPackIndexWriter, createPackObjectStore, createPackReader, decodeObjectHeader, decodeOfsDeltaOffset, decodeVarint, encodeObjectHeader, encodeOfsDeltaOffset, encodeVarint, packObjectToRaw };

package/dist/pack/object-header.d.mts

@@ -0,0 +1,36 @@
+//#region src/pack/object-header.d.ts
+/**
+ * Packfile 对象头部编码/解码
+ */
+/**
+ * 解码 Packfile 对象头部的变长整数
+ *
+ * 对象头部格式：
+ * - 第 1 字节：高 3 位是类型，低 4 位是大小
+ * - 后续字节：高 1 位是继续标志，低 7 位是大小
+ *
+ * @param buf - 数据缓冲区
+ * @param offset - 起始偏移量
+ * @returns [类型编号, 大小, 消耗的字节数]
+ *
+ * @example
+ * ```ts
+ * const [type, size, bytesRead] = decodeObjectHeader(buf, 0);
+ * ```
+ */
+declare function decodeObjectHeader(buf: Buffer, offset: number): [type: number, size: number, bytesRead: number];
+/**
+ * 编码 Packfile 对象头部的变长整数
+ *
+ * @param type - 对象类型编号（1-7）
+ * @param size - 对象大小
+ * @returns 编码后的字节缓冲区
+ *
+ * @example
+ * ```ts
+ * const header = encodeObjectHeader(3, 11);
+ * ```
+ */
+declare function encodeObjectHeader(type: number, size: number): Buffer;
+//#endregion
+export { decodeObjectHeader, encodeObjectHeader };

package/dist/pack/object-header.mjs

@@ -0,0 +1,72 @@
+import { InvalidPackError } from "../core/errors.mjs";
+//#region src/pack/object-header.ts
+/**
+* Packfile 对象头部编码/解码
+*/
+/**
+* 解码 Packfile 对象头部的变长整数
+*
+* 对象头部格式：
+* - 第 1 字节：高 3 位是类型，低 4 位是大小
+* - 后续字节：高 1 位是继续标志，低 7 位是大小
+*
+* @param buf - 数据缓冲区
+* @param offset - 起始偏移量
+* @returns [类型编号, 大小, 消耗的字节数]
+*
+* @example
+* ```ts
+* const [type, size, bytesRead] = decodeObjectHeader(buf, 0);
+* ```
+*/
+function decodeObjectHeader(buf, offset) {
+	if (offset >= buf.length) throw new InvalidPackError("Unexpected end of data in object header");
+	const firstByte = buf[offset];
+	const type = firstByte >> 4 & 7;
+	let size = firstByte & 15;
+	let shift = 4;
+	let bytesRead = 1;
+	if (firstByte & 128) {
+		let byte;
+		do {
+			if (offset + bytesRead >= buf.length) throw new InvalidPackError("Unexpected end of data in variable-length integer");
+			byte = buf[offset + bytesRead];
+			size |= (byte & 127) << shift;
+			shift += 7;
+			bytesRead++;
+		} while (byte & 128);
+	}
+	return [
+		type,
+		size,
+		bytesRead
+	];
+}
+/**
+* 编码 Packfile 对象头部的变长整数
+*
+* @param type - 对象类型编号（1-7）
+* @param size - 对象大小
+* @returns 编码后的字节缓冲区
+*
+* @example
+* ```ts
+* const header = encodeObjectHeader(3, 11);
+* ```
+*/
+function encodeObjectHeader(type, size) {
+	const bytes = [];
+	let byte = (type & 7) << 4 | size & 15;
+	size >>>= 4;
+	if (size > 0) byte |= 128;
+	bytes.push(byte);
+	while (size > 0) {
+		byte = size & 127;
+		size >>>= 7;
+		if (size > 0) byte |= 128;
+		bytes.push(byte);
+	}
+	return Buffer.from(bytes);
+}
+//#endregion
+export { decodeObjectHeader, encodeObjectHeader };

package/dist/pack/ofs-delta-offset.d.mts

@@ -0,0 +1,35 @@
+//#region src/pack/ofs-delta-offset.d.ts
+/**
+ * Packfile ofs_delta 偏移量编码/解码
+ */
+/**
+ * 解码 ofs_delta 的负偏移量
+ *
+ * ofs_delta 使用特殊的变长编码表示相对于当前对象的偏移量。
+ * 编码方式：每个字节的最高位是继续标志，低 7 位是数据。
+ * 后续字节需要先加 1 再左移，以支持更大的偏移量。
+ *
+ * @param buf - 数据缓冲区
+ * @param offset - 起始偏移量
+ * @returns [偏移量, 消耗的字节数]
+ *
+ * @example
+ * ```ts
+ * const [value, bytesRead] = decodeOfsDeltaOffset(buf, 0);
+ * ```
+ */
+declare function decodeOfsDeltaOffset(buf: Buffer, offset: number): [offsetValue: number, bytesRead: number];
+/**
+ * 编码 ofs_delta 的负偏移量
+ *
+ * @param offsetValue - 偏移量（正数，表示向后偏移的字节数）
+ * @returns 编码后的字节缓冲区
+ *
+ * @example
+ * ```ts
+ * const encoded = encodeOfsDeltaOffset(123);
+ * ```
+ */
+declare function encodeOfsDeltaOffset(offsetValue: number): Buffer;
+//#endregion
+export { decodeOfsDeltaOffset, encodeOfsDeltaOffset };

package/dist/pack/ofs-delta-offset.mjs

@@ -0,0 +1,59 @@
+import { InvalidPackError } from "../core/errors.mjs";
+//#region src/pack/ofs-delta-offset.ts
+/**
+* Packfile ofs_delta 偏移量编码/解码
+*/
+/**
+* 解码 ofs_delta 的负偏移量
+*
+* ofs_delta 使用特殊的变长编码表示相对于当前对象的偏移量。
+* 编码方式：每个字节的最高位是继续标志，低 7 位是数据。
+* 后续字节需要先加 1 再左移，以支持更大的偏移量。
+*
+* @param buf - 数据缓冲区
+* @param offset - 起始偏移量
+* @returns [偏移量, 消耗的字节数]
+*
+* @example
+* ```ts
+* const [value, bytesRead] = decodeOfsDeltaOffset(buf, 0);
+* ```
+*/
+function decodeOfsDeltaOffset(buf, offset) {
+	if (offset >= buf.length) throw new InvalidPackError("Unexpected end of data in ofs_delta offset");
+	let byte = buf[offset];
+	let value = byte & 127;
+	let bytesRead = 1;
+	while (byte & 128) {
+		if (offset + bytesRead >= buf.length) throw new InvalidPackError("Unexpected end of data in ofs_delta offset");
+		byte = buf[offset + bytesRead];
+		value = value + 1 << 7 | byte & 127;
+		bytesRead++;
+	}
+	return [value, bytesRead];
+}
+/**
+* 编码 ofs_delta 的负偏移量
+*
+* @param offsetValue - 偏移量（正数，表示向后偏移的字节数）
+* @returns 编码后的字节缓冲区
+*
+* @example
+* ```ts
+* const encoded = encodeOfsDeltaOffset(123);
+* ```
+*/
+function encodeOfsDeltaOffset(offsetValue) {
+	const bytes = [];
+	let value = offsetValue;
+	bytes.unshift(value & 127);
+	value >>>= 7;
+	while (value > 0) {
+		value--;
+		bytes.unshift(value & 127 | 128);
+		value >>>= 7;
+	}
+	return Buffer.from(bytes);
+}
+//#endregion
+export { decodeOfsDeltaOffset, encodeOfsDeltaOffset };

package/dist/pack/pack-builder-types.d.mts

@@ -0,0 +1,19 @@
+//#region src/pack/pack-builder-types.d.ts
+/**
+ * Packfile 构建器共享类型
+ */
+/**
+ * Packfile 构建结果
+ */
+interface PackBuildResult {
+  /** packfile 文件路径 */
+  packPath: string;
+  /** 索引文件路径 */
+  idxPath: string;
+  /** packfile 的 SHA-1 校验和 */
+  checksum: string;
+  /** 打包的对象数量 */
+  objectCount: number;
+}
+//#endregion
+export { PackBuildResult };

package/dist/pack/pack-builder.d.mts

@@ -0,0 +1,52 @@
+import { RawGitObject, SHA1 } from "../core/types.mjs";
+import { PackBuildResult } from "./pack-builder-types.mjs";
+
+//#region src/pack/pack-builder.d.ts
+/**
+ * Packfile 构建器接口
+ */
+interface PackBuilder {
+  /** 获取已添加的对象数量 */
+  readonly objectCount: number;
+  /**
+   * 添加一个原始对象
+   *
+   * @param raw - 原始 Git 对象
+   * @returns 对象的 SHA-1 哈希
+   */
+  addRaw(raw: RawGitObject): SHA1;
+  /**
+   * 构建 packfile 和索引文件
+   *
+   * @returns 构建结果，包含文件路径和校验和
+   *
+   * @example
+   * ```ts
+   * const result = builder.build();
+   * console.log(`Packfile: ${result.packPath}`);
+   * console.log(`Index: ${result.idxPath}`);
+   * ```
+   */
+  build(): PackBuildResult;
+}
+/**
+ * 创建 Packfile 构建器
+ *
+ * @param gitDir - .git 目录的路径
+ * @returns Packfile 构建器实例
+ *
+ * @example
+ * ```ts
+ * const builder = createPackBuilder("/path/to/.git");
+ *
+ * // 添加原始对象
+ * builder.addRaw(raw);
+ *
+ * // 构建并写入
+ * const result = builder.build();
+ * console.log(`已打包 ${result.objectCount} 个对象到 ${result.packPath}`);
+ * ```
+ */
+declare function createPackBuilder(gitDir: string): PackBuilder;
+//#endregion
+export { PackBuilder, createPackBuilder };

package/dist/pack/pack-builder.mjs

@@ -0,0 +1,80 @@
+import { createPackIndexWriter } from "./pack-index-writer.mjs";
+import { buildEncodedPack, toEncodedPackObject } from "./pack-encoding.mjs";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/pack/pack-builder.ts
+/**
+* Packfile 构建器
+*
+* 将 loose objects 打包成新的 packfile 和索引文件，
+* 并写入到 .git/objects/pack/ 目录。
+*
+* 这是 `git repack` 和 `git gc` 的核心功能。
+*
+* @example
+* ```ts
+* const builder = createPackBuilder(gitDir);
+* builder.addObject(blob);
+* builder.addObject(commit);
+* const result = builder.build();
+* // result => { packPath, idxPath, checksum, objectCount }
+* ```
+*/
+/**
+* 创建 Packfile 构建器
+*
+* @param gitDir - .git 目录的路径
+* @returns Packfile 构建器实例
+*
+* @example
+* ```ts
+* const builder = createPackBuilder("/path/to/.git");
+*
+* // 添加原始对象
+* builder.addRaw(raw);
+*
+* // 构建并写入
+* const result = builder.build();
+* console.log(`已打包 ${result.objectCount} 个对象到 ${result.packPath}`);
+* ```
+*/
+function createPackBuilder(gitDir) {
+	const objects = [];
+	const hashes = /* @__PURE__ */ new Set();
+	function addRaw(raw) {
+		const entry = toEncodedPackObject(raw);
+		const hash = entry.hash;
+		if (hashes.has(hash)) return hash;
+		objects.push(entry);
+		hashes.add(hash);
+		return hash;
+	}
+	function build() {
+		const packDir = join(gitDir, "objects", "pack");
+		mkdirSync(packDir, { recursive: true });
+		const encoded = buildEncodedPack(objects);
+		const idxWriter = createPackIndexWriter();
+		for (const entry of encoded.entries) idxWriter.addEntry(entry);
+		const idxData = idxWriter.build(encoded.packChecksum);
+		const checksumHex = encoded.packChecksum.toString("hex");
+		const packPath = join(packDir, `pack-${checksumHex}.pack`);
+		const idxPath = join(packDir, `pack-${checksumHex}.idx`);
+		writeFileSync(packPath, encoded.packData);
+		writeFileSync(idxPath, idxData);
+		return {
+			packPath,
+			idxPath,
+			checksum: checksumHex,
+			objectCount: objects.length
+		};
+	}
+	return {
+		get objectCount() {
+			return objects.length;
+		},
+		addRaw,
+		build
+	};
+}
+//#endregion
+export { createPackBuilder };

package/dist/pack/pack-encoding.mjs

@@ -0,0 +1,76 @@
+import { PACK_SIGNATURE, objectTypeToNumber } from "./constants.mjs";
+import { encodeObjectHeader } from "./object-header.mjs";
+import { crc32Value } from "./crc32.mjs";
+import { createHash } from "node:crypto";
+import { deflateSync } from "node:zlib";
+//#region src/pack/pack-encoding.ts
+/**
+* Packfile 编码共享逻辑
+*/
+/**
+* 将原始对象标准化为 pack 编码条目
+*
+* RawGitObject 的 { type, hash, content } 直接映射到 EncodedPackObject 的
+* { type, hash, data }，无需额外哈希计算或序列化。
+*
+* @param raw - 原始对象
+* @returns 编码条目
+*
+* @example
+* ```ts
+* const entry = toEncodedPackObject(raw);
+* ```
+*/
+function toEncodedPackObject(raw) {
+	return {
+		type: raw.type,
+		hash: raw.hash,
+		data: raw.content
+	};
+}
+/**
+* 构建 packfile 二进制内容，并返回索引所需元数据
+*
+* @param objects - 已标准化的编码条目
+* @returns pack 数据和索引条目
+*
+* @example
+* ```ts
+* const result = buildEncodedPack(entries);
+* ```
+*/
+function buildEncodedPack(objects) {
+	const packParts = [];
+	const entries = [];
+	packParts.push(createPackHeader(objects.length));
+	let currentOffset = packParts[0].length;
+	for (const object of objects) {
+		const objectHeader = encodeObjectHeader(objectTypeToNumber(object.type), object.data.length);
+		const compressed = deflateSync(object.data);
+		const objectData = Buffer.concat([objectHeader, compressed]);
+		entries.push({
+			hash: object.hash,
+			offset: currentOffset,
+			crc32: crc32Value(objectData)
+		});
+		packParts.push(objectHeader, compressed);
+		currentOffset += objectData.length;
+	}
+	const packWithoutChecksum = Buffer.concat(packParts);
+	const packChecksum = createHash("sha1").update(packWithoutChecksum).digest();
+	return {
+		packWithoutChecksum,
+		packChecksum,
+		packData: Buffer.concat([packWithoutChecksum, packChecksum]),
+		entries
+	};
+}
+function createPackHeader(objectCount) {
+	const header = Buffer.alloc(12);
+	PACK_SIGNATURE.copy(header, 0);
+	header.writeUInt32BE(2, 4);
+	header.writeUInt32BE(objectCount, 8);
+	return header;
+}
+//#endregion
+export { buildEncodedPack, toEncodedPackObject };