nano-git 0.1.0 → 0.2.0

package/README.md

@@ -8,13 +8,14 @@
 - ✅ **SHA-1 哈希计算** — 与 Git 完全兼容的对象哈希
 - ✅ **Git 对象模型** — 支持 blob、tree、commit、tag 四种对象类型
 - ✅ **对象序列化/反序列化** — 完整的二进制格式支持
-- ✅ **对象存储** — 文件系统存储和内存存储两种模式
+- ✅ **对象存储** — 文件系统存储、内存存储和 SQLite 存储三种模式
 - ✅ **Packfile 支持** — 读取、写入、索引生成、delta 编解码
 - ✅ **引用管理** — refs 验证、解析、存储（文件系统 + 内存）
 - ✅ **仓库 API** — 类似 Git plumbing 命令的高层接口（init、hash-object、cat-file、commit-tree、update-ref 等）
 - ✅ **增量 Tree Patch** — 不经暂存区直接修改目录结构（`patchTree`、`readTree`、`walkTree`）
 - ✅ **可达性遍历与 GC** — 基于 refs 的可达对象收集、repack、gc
 - ✅ **Smart HTTP 传输** — 基于 Bun fetch 的 Git 协议客户端，支持 `fetch()`/`push()` 与完整的 Import Session 物化流程
+- ✅ **远端查询 API** — 将 refs 快照、`object-info` 等纯远端能力独立出 `Repository`
 - ✅ **类型安全** — 完整的 TypeScript 类型定义
 - ✅ **Reference Transaction** — 批量 ref 更新的原子性保障，支持 Hooks 回调与自动回滚
 
@@ -55,6 +56,22 @@ await repo.fetch("https://github.com/user/repo.git");
 console.log(repo.listBranches());
 ```
 
+### 查询远端 refs / object-info
+
+```typescript
+import { createHttpRemote } from "nano-git/remote/http";
+
+const remote = createHttpRemote({
+  url: "https://github.com/user/repo.git",
+});
+
+const snapshot = await remote.readRefAdvertisement();
+console.log(snapshot.defaultBranch);
+
+const info = await remote.fetchObjectInfo(["95d09f2b10159347eece71399a7e2e907ea3df4f"]);
+console.log(info.objects[0]?.size);
+```
+
 ### 内存仓库完整工作流
 
 ```typescript
@@ -138,6 +155,43 @@ repo.updateRef("refs/heads/main", commitHash);
 
 `openRepository()` 默认会同时读取 `.git/objects/` 下的 loose objects 和 `.git/objects/pack/` 下的 packed objects，因此可以直接打开经过 `git gc` 或 `git repack` 的真实仓库（包括裸仓库）。搭配 `initRepository()` 的第二个参数可初始化为裸仓库布局。
 
+### 使用 SQLite 仓库（Bun 运行时）
+
+适用于需要持久化但又不想管理松散文件的场景——
+所有对象和引用存在一个 `.sqlite` 文件中。
+
+```typescript
+import { createSqliteRepository } from "nano-git/repository/sqlite";
+
+// 创建或打开 SQLite 持久化仓库（支持 using 自动释放）
+using repo = createSqliteRepository("/tmp/cache.sqlite");
+
+// 与普通 repo 使用方式完全一致
+const hash = repo.writeBlob(Buffer.from("persistent data"));
+const treeHash = repo.createTree([{ mode: "100644", name: "data.txt", hash }]);
+const commitHash = repo.createCommit(treeHash, [], "SQLite commit", {
+  name: "You",
+  email: "you@example.com",
+  timestamp: Math.floor(Date.now() / 1000),
+  timezone: "+0800",
+});
+console.log(`Committed: ${commitHash}`);
+
+// 作用域结束时自动关闭数据库连接
+```
+
+也可拆分使用底层后端：
+
+```typescript
+import { createSqliteRepositoryBackend } from "nano-git/backend/sqlite";
+import { createRepository } from "nano-git/repository/core";
+
+const backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+const repo = createRepository(backend);
+// 用完记得释放
+backend[Symbol.dispose]();
+```
+
 ### 生成 Packfile
 
 ```typescript
@@ -305,6 +359,8 @@ bun run examples/demo.ts
 
 本库默认入口 `"nano-git"` 直接提供高频的纯计算能力：类型、错误、对象编解码、refs 工具和 SHA-1 工具。
 带 `node:fs` / `node:zlib` 的运行时能力通过子路径显式导入，例如 `nano-git/repository/file`、`nano-git/pack`、`nano-git/transport/http`。
+纯远端查询能力通过 `nano-git/remote/http` 导入。
+基于 `bun:sqlite` 的存储后端通过 `nano-git/odb/sqlite`、`nano-git/refs/sqlite`、`nano-git/backend/sqlite`、`nano-git/repository/sqlite` 等子路径导入。
 tree-shaking 主要依赖模块本身的无副作用结构，而不是把所有 API 都拆成叶子级子路径。完整入口表见 `package.json` 的 `exports` 与 `src/index.ts` 的 JSDoc。
 
 ## Git 对象模型
@@ -381,6 +437,7 @@ bun test
 - [x] 可达性遍历与 GC（repack、gc）
 - [x] **Smart HTTP 传输** — pkt-line 编解码、ref 广告解析、side-band 解复用、Fetch / Push 协议、Import Session 集成
 - [x] **Reference Transaction** — 批量 ref 更新原子性、lock-then-rename 文件事务、生命周期 Hooks
+- [x] **SQLite 存储后端** — 基于 `bun:sqlite` 的单文件持久化，支持对象/refs/shallow 存储、ACID 事务、`Symbol.dispose` 生命周期管理
 
 - [x] **Smart HTTP 服务端（upload-pack）** — 类 git-http-backend、框架无关的 HTTP handler，支持 ls-refs 和 fetch 命令，协议实现与编排器解耦
 - [x] **Smart HTTP 服务端（v1 receive-pack）** — 服务端 push 支持，基于 v1 协议，含 ref 广告、packfile 解包、ref 校验与 report-status

package/dist/backend/sqlite.d.mts

@@ -0,0 +1,44 @@
+import { RepositoryBackend } from "./types.mjs";
+
+//#region src/backend/sqlite.d.ts
+/** 创建 SQLite 仓库后端的可选参数 */
+interface CreateSqliteRepositoryBackendOptions {
+  /** 开启 WAL 模式，默认 true */
+  readonly walMode?: boolean;
+}
+/**
+ * SQLite 仓库后端（含资源释放能力）
+ *
+ * 在 RepositoryBackend 的基础上增加了 [Symbol.dispose]()，
+ * 支持 `using backend = createSqliteRepositoryBackend(...)` 语法。
+ */
+interface SqliteRepositoryBackend extends RepositoryBackend {
+  /** 释放 SQLite 数据库连接 */
+  [Symbol.dispose](): void;
+}
+/**
+ * 创建基于 SQLite 文件的完整仓库后端
+ *
+ * 内部创建 Database 实例并组合三个子 store。
+ * 返回的 backend 实现了 [Symbol.dispose]()，可使用 `using` 语法
+ * 或在不再使用时手动调用 `backend[Symbol.dispose]()`。
+ *
+ * @param dbPath - SQLite 数据库文件路径
+ * @returns 实现了 SqliteRepositoryBackend 的仓库后端（可用 `using` 管理）
+ *
+ * @example
+ * ```ts
+ * // 使用 using 自动释放（推荐）
+ * using backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+ * const repo = createRepository(backend);
+ *
+ * // 或手动管理
+ * const backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+ * const repo = createRepository(backend);
+ * // ... 使用完毕 ...
+ * backend[Symbol.dispose]();
+ * ```
+ */
+declare function createSqliteRepositoryBackend(dbPath: string, options?: CreateSqliteRepositoryBackendOptions): SqliteRepositoryBackend;
+//#endregion
+export { CreateSqliteRepositoryBackendOptions, SqliteRepositoryBackend, createSqliteRepositoryBackend };

package/dist/backend/sqlite.mjs

@@ -0,0 +1,59 @@
+import { HEADS_PREFIX, HEAD_REF } from "../core/types/refs.mjs";
+import { createSqliteObjectStore } from "../odb/sqlite.mjs";
+import { createSqliteRefStore } from "../refs/sqlite.mjs";
+import { createSqliteShallowStore } from "../refs/shallow/sqlite.mjs";
+import { Database } from "bun:sqlite";
+//#region src/backend/sqlite.ts
+/**
+* 基于 SQLite 的仓库后端
+*
+* 将 SQLite 中的 objects、refs、shallow 存储
+* 组合为统一的 RepositoryBackend。
+*
+* 支持 [Symbol.dispose]() 释放数据库连接，
+* 可使用 `using` 语法管理生命周期。
+*/
+/**
+* 创建基于 SQLite 文件的完整仓库后端
+*
+* 内部创建 Database 实例并组合三个子 store。
+* 返回的 backend 实现了 [Symbol.dispose]()，可使用 `using` 语法
+* 或在不再使用时手动调用 `backend[Symbol.dispose]()`。
+*
+* @param dbPath - SQLite 数据库文件路径
+* @returns 实现了 SqliteRepositoryBackend 的仓库后端（可用 `using` 管理）
+*
+* @example
+* ```ts
+* // 使用 using 自动释放（推荐）
+* using backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+* const repo = createRepository(backend);
+*
+* // 或手动管理
+* const backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+* const repo = createRepository(backend);
+* // ... 使用完毕 ...
+* backend[Symbol.dispose]();
+* ```
+*/
+function createSqliteRepositoryBackend(dbPath, options = {}) {
+	const db = new Database(dbPath);
+	if (options.walMode !== false) db.run("PRAGMA journal_mode = WAL");
+	db.run("CREATE TABLE IF NOT EXISTS objects (hash TEXT PRIMARY KEY, type TEXT NOT NULL, content BLOB NOT NULL)");
+	db.run("CREATE TABLE IF NOT EXISTS refs (name TEXT PRIMARY KEY, target TEXT NOT NULL)");
+	db.run("CREATE TABLE IF NOT EXISTS shallow (hash TEXT PRIMARY KEY)");
+	db.run("INSERT OR IGNORE INTO refs (name, target) VALUES (?, ?)", [HEAD_REF, `ref: ${HEADS_PREFIX}main`]);
+	return {
+		gitDir: dbPath,
+		objects: createSqliteObjectStore(db),
+		refs: createSqliteRefStore(db),
+		shallow: createSqliteShallowStore(db),
+		packs: null,
+		/** 释放 SQLite 数据库连接 */
+		[Symbol.dispose]() {
+			db.close();
+		}
+	};
+}
+//#endregion
+export { createSqliteRepositoryBackend };

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 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 { RemoteSource } from "./remote/types.mjs";
 import { FileRepository, Repository } from "./repository/types.mjs";
 import { hashData, hashObject } from "./core/hash-digest.mjs";
 import { isValidSHA1 } from "./core/hash-path.mjs";
@@ -13,4 +14,4 @@ import { deserialize, deserializeContent, serialize, serializeContent } from "./
 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 };
+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 RemoteSource, 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/odb/sqlite.d.mts

@@ -0,0 +1,23 @@
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { Database } from "bun:sqlite";
+
+//#region src/odb/sqlite.d.ts
+/**
+ * 创建基于 SQLite 的对象数据库
+ *
+ * @param db - 已打开的 bun:sqlite Database 实例
+ * @returns 符合 ObjectDatabase 接口的存储后端
+ *
+ * @example
+ * ```ts
+ * import { Database } from "bun:sqlite";
+ * const db = new Database("/tmp/repo.sqlite");
+ * const store = createSqliteObjectStore(db);
+ *
+ * store.ingest(raw);
+ * const obj = store.read(hash);
+ * ```
+ */
+declare function createSqliteObjectStore(db: Database): ObjectDatabase;
+//#endregion
+export { createSqliteObjectStore };

package/dist/odb/sqlite.mjs

@@ -0,0 +1,83 @@
+import { ObjectNotFoundError } from "../core/errors.mjs";
+import { sha1 } from "../core/types.mjs";
+import { hashObject } from "../core/hash-digest.mjs";
+//#region src/odb/sqlite.ts
+/**
+* 基于 SQLite 的对象数据库（raw-first）
+*
+* 所有对象存储在 SQLite 数据库的 objects 表中。
+* 使用 INSERT OR IGNORE 实现幂等写入，使用 db.transaction() 实现批量原子写入。
+*
+* 表创建由上层 createSqliteRepositoryBackend 负责，
+* 本模块只操作已存在的表，不负责 DDL。
+*/
+/**
+* 创建基于 SQLite 的对象数据库
+*
+* @param db - 已打开的 bun:sqlite Database 实例
+* @returns 符合 ObjectDatabase 接口的存储后端
+*
+* @example
+* ```ts
+* import { Database } from "bun:sqlite";
+* const db = new Database("/tmp/repo.sqlite");
+* const store = createSqliteObjectStore(db);
+*
+* store.ingest(raw);
+* const obj = store.read(hash);
+* ```
+*/
+function createSqliteObjectStore(db) {
+	const selectStmt = db.query("SELECT hash, type, content FROM objects WHERE hash = ?");
+	const existsStmt = db.query("SELECT 1 FROM objects WHERE hash = ?");
+	const insertStmt = db.query("INSERT OR IGNORE INTO objects (hash, type, content) VALUES (?, ?, ?)");
+	const deleteStmt = db.query("DELETE FROM objects WHERE hash = ?");
+	const listStmt = db.query("SELECT hash FROM objects ORDER BY hash");
+	/** 批量插入的事务包装 */
+	const ingestManyTx = db.transaction((objects) => {
+		for (const raw of objects) {
+			const expectedHash = hashObject(raw.type, raw.content);
+			if (expectedHash !== raw.hash) throw new Error(`RawGitObject hash mismatch: expected ${expectedHash}, got ${raw.hash}`);
+			insertStmt.run(raw.hash, raw.type, raw.content);
+		}
+	});
+	return {
+		ingest(raw) {
+			const expectedHash = hashObject(raw.type, raw.content);
+			if (expectedHash !== raw.hash) throw new Error(`RawGitObject hash mismatch: expected ${expectedHash}, got ${raw.hash}`);
+			insertStmt.run(raw.hash, raw.type, raw.content);
+		},
+		ingestMany(objects) {
+			ingestManyTx(objects);
+		},
+		read(hash) {
+			const row = selectStmt.get(hash);
+			if (!row) throw new ObjectNotFoundError(hash);
+			return {
+				hash: sha1(row.hash),
+				type: row.type,
+				content: Buffer.from(row.content)
+			};
+		},
+		tryRead(hash) {
+			const row = selectStmt.get(hash);
+			if (!row) return;
+			return {
+				hash: sha1(row.hash),
+				type: row.type,
+				content: Buffer.from(row.content)
+			};
+		},
+		exists(hash) {
+			return existsStmt.get(hash) !== null;
+		},
+		list() {
+			return listStmt.all().map((row) => sha1(row.hash));
+		},
+		delete(hash) {
+			deleteStmt.run(hash);
+		}
+	};
+}
+//#endregion
+export { createSqliteObjectStore };

package/dist/refs/shallow/sqlite.d.mts

@@ -0,0 +1,23 @@
+import { ShallowStore } from "../../core/types/shallow.mjs";
+import { Database } from "bun:sqlite";
+
+//#region src/refs/shallow/sqlite.d.ts
+/**
+ * 创建基于 SQLite 的 shallow 边界存储
+ *
+ * @param db - 已打开的 bun:sqlite Database 实例
+ * @returns 符合 ShallowStore 接口的存储后端
+ *
+ * @example
+ * ```ts
+ * import { Database } from "bun:sqlite";
+ * const db = new Database("/tmp/repo.sqlite");
+ * const store = createSqliteShallowStore(db);
+ *
+ * store.write([hashA, hashB]);
+ * console.log(store.isShallow(hashA)); // true
+ * ```
+ */
+declare function createSqliteShallowStore(db: Database): ShallowStore;
+//#endregion
+export { createSqliteShallowStore };

package/dist/refs/shallow/sqlite.mjs

@@ -0,0 +1,61 @@
+import { sha1 } from "../../core/types.mjs";
+//#region src/refs/shallow/sqlite.ts
+/**
+* 基于 SQLite 的 Shallow 存储
+*
+* 所有 shallow 边界存储在 SQLite 数据库的 shallow 表中。
+* write 使用 DELETE + INSERT 全量替换模式（与 memory/file 后端一致）。
+* applyUpdate 使用 SQL 事务做增量更新。
+*
+* 表创建由上层 createSqliteRepositoryBackend 负责，
+* 本模块只操作已存在的表，不负责 DDL。
+*/
+/**
+* 创建基于 SQLite 的 shallow 边界存储
+*
+* @param db - 已打开的 bun:sqlite Database 实例
+* @returns 符合 ShallowStore 接口的存储后端
+*
+* @example
+* ```ts
+* import { Database } from "bun:sqlite";
+* const db = new Database("/tmp/repo.sqlite");
+* const store = createSqliteShallowStore(db);
+*
+* store.write([hashA, hashB]);
+* console.log(store.isShallow(hashA)); // true
+* ```
+*/
+function createSqliteShallowStore(db) {
+	const selectAllStmt = db.query("SELECT hash FROM shallow ORDER BY hash");
+	const selectExistsStmt = db.query("SELECT 1 FROM shallow WHERE hash = ?");
+	const deleteAllStmt = db.query("DELETE FROM shallow");
+	const insertStmt = db.query("INSERT OR IGNORE INTO shallow (hash) VALUES (?)");
+	const deleteOneStmt = db.query("DELETE FROM shallow WHERE hash = ?");
+	/** 全量替换事务 */
+	const replaceAllTx = db.transaction((boundaries) => {
+		deleteAllStmt.run();
+		for (const hash of boundaries) insertStmt.run(hash);
+	});
+	/** 增量更新事务 */
+	const applyUpdateTx = db.transaction((update) => {
+		for (const hash of update.unshallow) deleteOneStmt.run(hash);
+		for (const hash of update.shallow) insertStmt.run(hash);
+	});
+	return {
+		read() {
+			return selectAllStmt.all().map((row) => sha1(row.hash));
+		},
+		write(boundaries) {
+			replaceAllTx(boundaries);
+		},
+		applyUpdate(update) {
+			applyUpdateTx(update);
+		},
+		isShallow(hash) {
+			return selectExistsStmt.get(hash) !== null;
+		}
+	};
+}
+//#endregion
+export { createSqliteShallowStore };

package/dist/refs/sqlite.d.mts

@@ -0,0 +1,23 @@
+import { RefStore } from "../core/types/refs.mjs";
+import { Database } from "bun:sqlite";
+
+//#region src/refs/sqlite.d.ts
+/**
+ * 创建基于 SQLite 的 RefStore
+ *
+ * @param db - 已打开的 bun:sqlite Database 实例（生命周期由调用方管理）
+ * @returns 符合 RefStore 接口的存储后端（含事务支持）
+ *
+ * @example
+ * ```ts
+ * import { Database } from "bun:sqlite";
+ * const db = new Database("/tmp/repo.sqlite");
+ * const store = createSqliteRefStore(db);
+ *
+ * store.write("refs/heads/main", "abc123");
+ * const content = store.read("refs/heads/main");
+ * ```
+ */
+declare function createSqliteRefStore(db: Database): RefStore;
+//#endregion
+export { createSqliteRefStore };

package/dist/refs/sqlite.mjs

@@ -0,0 +1,135 @@
+import { RefNotFoundError, TransactionError } from "../core/errors.mjs";
+import { validateRefName, validateRefPrefix } from "./names.mjs";
+//#region src/refs/sqlite.ts
+/**
+* 基于 SQLite 的 Refs 存储
+*
+* 所有引用存储在 SQLite 数据库的 refs 表中。
+* 使用 INSERT OR REPLACE 实现幂等写入，使用 db.transaction() 实现事务原子性。
+*
+* 表创建由上层 createSqliteRepositoryBackend 负责，
+* 本模块只操作已存在的表，不负责 DDL。
+*/
+/**
+* 创建基于 SQLite 的 RefStore
+*
+* @param db - 已打开的 bun:sqlite Database 实例（生命周期由调用方管理）
+* @returns 符合 RefStore 接口的存储后端（含事务支持）
+*
+* @example
+* ```ts
+* import { Database } from "bun:sqlite";
+* const db = new Database("/tmp/repo.sqlite");
+* const store = createSqliteRefStore(db);
+*
+* store.write("refs/heads/main", "abc123");
+* const content = store.read("refs/heads/main");
+* ```
+*/
+function createSqliteRefStore(db) {
+	const selectStmt = db.query("SELECT target FROM refs WHERE name = ?");
+	const selectExistsStmt = db.query("SELECT 1 FROM refs WHERE name = ?");
+	const insertStmt = db.query("INSERT OR REPLACE INTO refs (name, target) VALUES (?, ?)");
+	const deleteStmt = db.query("DELETE FROM refs WHERE name = ?");
+	const listPrefixStmt = db.query("SELECT name FROM refs WHERE name >= ? AND name < ? ORDER BY name");
+	const listAllStmt = db.query("SELECT name FROM refs WHERE name LIKE 'refs/%' ORDER BY name");
+	/**
+	* 开启一个新的事务
+	*
+	* 所有变更暂存于 JS Map，commit() 时通过 SQLite 事务原子性写入。
+	*/
+	function beginTransaction(hooks) {
+		const pending = /* @__PURE__ */ new Map();
+		const snapshot = /* @__PURE__ */ new Map();
+		for (const row of listAllStmt.all()) {
+			const val = selectStmt.get(row.name);
+			if (val !== null) snapshot.set(row.name, val.target);
+		}
+		let committed = false;
+		return {
+			get pendingCount() {
+				return pending.size;
+			},
+			write(ref, content) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				pending.set(ref, content.trimEnd());
+			},
+			delete(ref) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				const inDb = selectExistsStmt.get(ref) !== null;
+				const inPending = pending.has(ref);
+				if (!inDb && !inPending) throw new RefNotFoundError(ref);
+				pending.set(ref, null);
+			},
+			commit() {
+				if (committed) throw new TransactionError("Transaction already committed");
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				try {
+					for (const hook of hooks ?? []) hook.onPrepare?.(txSnapshot);
+					db.transaction(() => {
+						for (const [ref, content] of pending) if (content === null) {
+							if (!snapshot.has(ref) && !selectExistsStmt.get(ref)) throw new RefNotFoundError(ref);
+							deleteStmt.run(ref);
+						} else insertStmt.run(ref, content);
+					})();
+					for (const hook of hooks ?? []) hook.onCommitted?.(txSnapshot);
+				} catch (e) {
+					for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+					throw e;
+				}
+			},
+			rollback() {
+				if (committed) return;
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+			}
+		};
+	}
+	return {
+		read(ref) {
+			validateRefName(ref);
+			return selectStmt.get(ref)?.target ?? null;
+		},
+		write(ref, content) {
+			validateRefName(ref);
+			insertStmt.run(ref, content.trimEnd());
+		},
+		delete(ref) {
+			validateRefName(ref);
+			if (!selectExistsStmt.get(ref)) throw new RefNotFoundError(ref);
+			deleteStmt.run(ref);
+		},
+		list(prefix) {
+			validateRefPrefix(prefix);
+			const end = prefix + "";
+			return listPrefixStmt.all(prefix, end).map((row) => row.name);
+		},
+		listAll() {
+			return listAllStmt.all().map((row) => row.name);
+		},
+		beginTransaction
+	};
+}
+/**
+* 将 pending Map 冻结为只读快照
+*/
+function freezePending(pending) {
+	const writes = [];
+	const deletes = [];
+	for (const [ref, content] of pending) if (content === null) deletes.push({ ref });
+	else writes.push({
+		ref,
+		content
+	});
+	return Object.freeze({
+		pendingCount: pending.size,
+		writes: Object.freeze(writes),
+		deletes: Object.freeze(deletes)
+	});
+}
+//#endregion
+export { createSqliteRefStore };

package/dist/remote/http.d.mts

@@ -0,0 +1,51 @@
+import { RemoteSource } from "./types.mjs";
+import { RefAdvertisement } from "../transport/protocol/types.mjs";
+import { LsRefsEntry, V2CapabilityAdvertisement } from "../transport/client/upload-pack/types.mjs";
+import { LsRefsOptions } from "../transport/client/upload-pack/ls-refs.mjs";
+import { ObjectInfoQueryResult } from "../transport/client/upload-pack/object-info.mjs";
+
+//#region src/remote/http.d.ts
+/**
+ * 远端 HTTP 查询接口
+ */
+interface HttpRemote {
+  /** 远端来源配置 */
+  readonly source: Readonly<RemoteSource>;
+  /** 读取 v2 能力广告 */
+  advertise(): Promise<V2CapabilityAdvertisement>;
+  /** 原样执行 ls-refs 查询 */
+  listRefs(options?: LsRefsOptions): Promise<LsRefsEntry[]>;
+  /** 读取适合高层 API 使用的 ref 快照 */
+  readRefAdvertisement(): Promise<RefAdvertisement>;
+  /** 查询对象元数据（协议 v2 object-info） */
+  fetchObjectInfo(oids: string[]): Promise<ObjectInfoQueryResult>;
+}
+/**
+ * 创建基于 Smart HTTP 的远端查询对象
+ *
+ * 适用于只依赖远端 URL / 认证信息的查询，
+ * 例如 refs 快照和 object-info，不需要本地 repo 上下文。
+ *
+ * @param source - 远端来源
+ * @returns 远端查询对象
+ *
+ * @example
+ * ```ts
+ * import { createHttpRemote } from "nano-git/remote/http";
+ *
+ * const remote = createHttpRemote({
+ *   url: "https://github.com/user/repo.git",
+ * });
+ *
+ * const snapshot = await remote.readRefAdvertisement();
+ * const info = await remote.fetchObjectInfo([
+ *   "95d09f2b10159347eece71399a7e2e907ea3df4f",
+ * ]);
+ *
+ * console.log(snapshot.defaultBranch);
+ * console.log(info.objects[0]?.size);
+ * ```
+ */
+declare function createHttpRemote(source: RemoteSource): HttpRemote;
+//#endregion
+export { HttpRemote, createHttpRemote };

package/dist/remote/http.mjs

@@ -0,0 +1,74 @@
+import { createV2HttpTransport } from "../transport/client/upload-pack/http.mjs";
+import { lsRefs, lsRefsToRefAdvertisement } from "../transport/client/upload-pack/ls-refs.mjs";
+import { objectInfo } from "../transport/client/upload-pack/object-info.mjs";
+//#region src/remote/http.ts
+/**
+* 基于 HTTP 的远端 Git 查询 API
+*
+* 将纯远端查询能力从 Repository 中拆出：
+* - refs 快照
+* - v2 object-info
+* - 协议能力广告
+*/
+/**
+* 创建基于 Smart HTTP 的远端查询对象
+*
+* 适用于只依赖远端 URL / 认证信息的查询，
+* 例如 refs 快照和 object-info，不需要本地 repo 上下文。
+*
+* @param source - 远端来源
+* @returns 远端查询对象
+*
+* @example
+* ```ts
+* import { createHttpRemote } from "nano-git/remote/http";
+*
+* const remote = createHttpRemote({
+*   url: "https://github.com/user/repo.git",
+* });
+*
+* const snapshot = await remote.readRefAdvertisement();
+* const info = await remote.fetchObjectInfo([
+*   "95d09f2b10159347eece71399a7e2e907ea3df4f",
+* ]);
+*
+* console.log(snapshot.defaultBranch);
+* console.log(info.objects[0]?.size);
+* ```
+*/
+function createHttpRemote(source) {
+	const frozenSource = Object.freeze({
+		url: source.url,
+		token: source.token,
+		headers: source.headers ? Object.freeze({ ...source.headers }) : void 0
+	});
+	const transport = createV2HttpTransport(frozenSource.url, {
+		token: frozenSource.token,
+		headers: frozenSource.headers
+	});
+	return {
+		source: frozenSource,
+		advertise() {
+			return transport.advertise();
+		},
+		listRefs(options) {
+			return lsRefs(transport, options);
+		},
+		async readRefAdvertisement() {
+			return lsRefsToRefAdvertisement(await lsRefs(transport, {
+				symrefs: true,
+				peel: true,
+				refPrefixes: [
+					"HEAD",
+					"refs/heads/",
+					"refs/tags/"
+				]
+			}));
+		},
+		fetchObjectInfo(oids) {
+			return objectInfo(transport, oids);
+		}
+	};
+}
+//#endregion
+export { createHttpRemote };

package/dist/remote/types.d.mts

@@ -0,0 +1,20 @@
+//#region src/remote/types.d.ts
+/**
+ * 远端来源类型定义
+ *
+ * 只描述"从哪里读"，不描述"写到哪里"。
+ * 可被远端查询 API 与仓库导入 API 共同复用。
+ */
+/**
+ * 远端 Git 数据来源
+ */
+interface RemoteSource {
+  /** 远端仓库 URL */
+  readonly url: string;
+  /** 认证 token（用于 bearer 或 basic auth） */
+  readonly token?: string;
+  /** 自定义请求头 */
+  readonly headers?: Record<string, string>;
+}
+//#endregion
+export { RemoteSource };

package/dist/repository/import/import-session-types.d.mts

@@ -1,21 +1,8 @@
 import { SHA1 } from "../../core/types.mjs";
+import { RemoteSource } from "../../remote/types.mjs";
 import { RefAdvertisement, RemoteRef } from "../../transport/protocol/types.mjs";
 
 //#region src/repository/import/import-session-types.d.ts
-/**
- * 远端 Git 数据来源
- *
- * 只描述"从哪里读"，不描述"写到哪里"。
- * ImportSource 不包含命名空间映射规则。
- */
-interface ImportSource {
-  /** 远端仓库 URL */
-  readonly url: string;
-  /** 认证 token（用于 bearer 或 basic auth） */
-  readonly token?: string;
-  /** 自定义请求头 */
-  readonly headers?: Record<string, string>;
-}
 /**
  * 远端 ref 视图
  *
@@ -244,7 +231,7 @@ interface ImportApplyResult {
  * 想刷新远端状态时，必须重新创建 session。
  */
 interface ImportSession {
-  readonly source: ImportSource;
+  readonly source: RemoteSource;
   readonly advertisement: RefAdvertisement;
   select(pattern: string): ImportView;
   selectRefs(patterns: readonly string[]): ImportView;
@@ -274,7 +261,7 @@ interface RepoImportOperations {
    * const branches = session.select("refs/heads/*");
    * ```
    */
-  openImportSession(source: ImportSource): Promise<ImportSession>;
+  openImportSession(source: RemoteSource): Promise<ImportSession>;
 }
 //#endregion
 export { RepoImportOperations };

package/dist/repository/ops/object-operations.mjs

@@ -1,7 +1,5 @@
 import { hashObject } from "../../core/hash-digest.mjs";
 import { readObject, writeObject } from "../../objects/raw.mjs";
-import { createV2HttpTransport } from "../../transport/client/upload-pack/http.mjs";
-import { objectInfo } from "../../transport/client/upload-pack/object-info.mjs";
 import { patchTree } from "../tree/tree-patch.mjs";
 //#region src/repository/ops/object-operations.ts
 /**
@@ -55,9 +53,6 @@ function createObjectRepositoryOperations(objects) {
 		},
 		patchTree(rootHash, ops) {
 			return patchTree(objects, rootHash, ops);
-		},
-		async fetchObjectInfo(url, oids, token) {
-			return objectInfo(createV2HttpTransport(url, { token }), oids);
 		}
 	};
 }

package/dist/repository/ops/object-types.d.mts

@@ -1,5 +1,4 @@
 import { GitAuthor, GitObject, SHA1, TreeEntry } from "../../core/types.mjs";
-import { ObjectInfoQueryResult } from "../../transport/client/upload-pack/object-info.mjs";
 import { TreePatchOp, TreePatchResult } from "../tree/tree-patch.mjs";
 
 //#region src/repository/ops/object-types.d.ts
@@ -67,26 +66,6 @@ interface RepositoryObjectOperations {
    * ```
    */
   patchTree(rootHash: SHA1, ops: TreePatchOp[]): TreePatchResult;
-  /**
-   * 查询远端对象信息（协议 v2 object-info）
-   *
-   * 批量查询远端对象的元数据（如 size），无需下载对象内容。
-   * 仅在远端支持 Git Wire 协议 v2 时可用。
-   *
-   * @param url - 远端仓库 URL
-   * @param oids - 要查询的 OID 列表
-   * @param token - 可选认证 token
-   * @returns 对象信息列表（含 size 等元数据）
-   *
-   * @example
-   * ```ts
-   * const result = await repo.fetchObjectInfo("https://github.com/user/repo", [
-   *   "95d09f2b10159347eece71399a7e2e907ea3df4f",
-   * ]);
-   * console.log(result.objects[0]?.size); // 文件大小
-   * ```
-   */
-  fetchObjectInfo(url: string, oids: string[], token?: string): Promise<ObjectInfoQueryResult>;
 }
 /**
  * 文件系统对象操作扩展

package/dist/repository/sqlite.d.mts

@@ -0,0 +1,28 @@
+import { CreateSqliteRepositoryBackendOptions } from "../backend/sqlite.mjs";
+import { Repository } from "./types.mjs";
+
+//#region src/repository/sqlite.d.ts
+/**
+ * 创建基于 SQLite 文件的持久化仓库
+ *
+ * 相比直接使用 createSqliteRepositoryBackend + createRepository，
+ * 此函数提供了更简洁的一步到位接口。
+ *
+ * @param dbPath - SQLite 数据库文件路径
+ * @param options - 可选参数（如 walMode）
+ * @returns 仓库实例（附带 [Symbol.dispose]()，可用 `using` 管理）
+ *
+ * @example
+ * ```ts
+ * // 使用 using 自动释放（推荐）
+ * using repo = createSqliteRepository("/tmp/repo.sqlite");
+ * repo.createBranch("main", repo.createTree([]));
+ * repo.writeBlob(Buffer.from("data"));
+ * // 作用域结束时自动关闭数据库连接
+ * ```
+ */
+declare function createSqliteRepository(dbPath: string, options?: CreateSqliteRepositoryBackendOptions): Repository & {
+  [Symbol.dispose](): void;
+};
+//#endregion
+export { createSqliteRepository };

package/dist/repository/sqlite.mjs

@@ -0,0 +1,45 @@
+import { createSqliteRepositoryBackend } from "../backend/sqlite.mjs";
+import { createRepository } from "./create.mjs";
+//#region src/repository/sqlite.ts
+/**
+* SQLite 仓库便捷创建函数
+*
+* 一键创建基于 SQLite 的持久化 Git 仓库。
+* 内部组合 createSqliteRepositoryBackend + createRepository，
+* 返回的 repo 自带 [Symbol.dispose]()，可用 `using` 管理生命周期。
+*
+* @example
+* ```ts
+* import { createSqliteRepository } from "nano-git/repository/sqlite";
+*
+* using repo = createSqliteRepository("/tmp/cache.sqlite");
+* const hash = repo.writeBlob(Buffer.from("hello world"));
+* // 作用域结束时自动 db.close()
+* ```
+*/
+/**
+* 创建基于 SQLite 文件的持久化仓库
+*
+* 相比直接使用 createSqliteRepositoryBackend + createRepository，
+* 此函数提供了更简洁的一步到位接口。
+*
+* @param dbPath - SQLite 数据库文件路径
+* @param options - 可选参数（如 walMode）
+* @returns 仓库实例（附带 [Symbol.dispose]()，可用 `using` 管理）
+*
+* @example
+* ```ts
+* // 使用 using 自动释放（推荐）
+* using repo = createSqliteRepository("/tmp/repo.sqlite");
+* repo.createBranch("main", repo.createTree([]));
+* repo.writeBlob(Buffer.from("data"));
+* // 作用域结束时自动关闭数据库连接
+* ```
+*/
+function createSqliteRepository(dbPath, options) {
+	const backend = createSqliteRepositoryBackend(dbPath, options);
+	const repo = createRepository(backend);
+	return Object.assign(repo, { [Symbol.dispose]: () => backend[Symbol.dispose]() });
+}
+//#endregion
+export { createSqliteRepository };

package/dist/transport/upload-pack.d.mts

@@ -1,7 +1,7 @@
 import { LsRefsEntry, ObjectInfoEntry, ObjectInfoResponse, V2CapabilityAdvertisement, V2CommandEntry, V2FetchRequest, V2FetchResponse, V2GitServiceTransport } from "./client/upload-pack/types.mjs";
+import { LsRefsError, LsRefsOptions, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse } from "./client/upload-pack/ls-refs.mjs";
 import { ObjectInfoError, ObjectInfoQueryResult, ObjectInfoResult, objectInfo, parseObjectInfoResponse } from "./client/upload-pack/object-info.mjs";
 import { V2CapabilityError, getCommandFeatures, hasCommand, parseV2CapabilityAdvertisement } from "./client/upload-pack/capability-advertisement.mjs";
 import { V2SmartHttpError, createV2HttpTransport } from "./client/upload-pack/http.mjs";
-import { LsRefsError, LsRefsOptions, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse } from "./client/upload-pack/ls-refs.mjs";
 import { V2FetchError, V2FetchParams, parseV2FetchResponse, v2Fetch, v2FetchObjects } from "./client/upload-pack/fetch.mjs";
 export { type LsRefsEntry, LsRefsError, type LsRefsOptions, type ObjectInfoEntry, ObjectInfoError, type ObjectInfoQueryResult, type ObjectInfoResponse, type ObjectInfoResult, type V2CapabilityAdvertisement, V2CapabilityError, type V2CommandEntry, V2FetchError, type V2FetchParams, type V2FetchRequest, type V2FetchResponse, type V2GitServiceTransport, V2SmartHttpError, createV2HttpTransport, getCommandFeatures, hasCommand, lsRefs, lsRefsToRefAdvertisement, objectInfo, parseLsRefsResponse, parseObjectInfoResponse, parseV2CapabilityAdvertisement, parseV2FetchResponse, v2Fetch, v2FetchObjects };

package/dist/transport/upload-pack.mjs

@@ -1,6 +1,6 @@
 import { V2CapabilityError, getCommandFeatures, hasCommand, parseV2CapabilityAdvertisement } from "./client/upload-pack/capability-advertisement.mjs";
 import { V2SmartHttpError, createV2HttpTransport } from "./client/upload-pack/http.mjs";
 import { LsRefsError, lsRefs, lsRefsToRefAdvertisement, parseLsRefsResponse } from "./client/upload-pack/ls-refs.mjs";
-import { V2FetchError, parseV2FetchResponse, v2Fetch, v2FetchObjects } from "./client/upload-pack/fetch.mjs";
 import { ObjectInfoError, objectInfo, parseObjectInfoResponse } from "./client/upload-pack/object-info.mjs";
+import { V2FetchError, parseV2FetchResponse, v2Fetch, v2FetchObjects } from "./client/upload-pack/fetch.mjs";
 export { LsRefsError, ObjectInfoError, V2CapabilityError, V2FetchError, V2SmartHttpError, createV2HttpTransport, getCommandFeatures, hasCommand, lsRefs, lsRefsToRefAdvertisement, objectInfo, parseLsRefsResponse, parseObjectInfoResponse, parseV2CapabilityAdvertisement, parseV2FetchResponse, v2Fetch, v2FetchObjects };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nano-git",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "files": [
     "dist"
   ],
@@ -11,11 +11,13 @@
     "./backend": "./src/backend/index.ts",
     "./backend/file": "./src/backend/file.ts",
     "./backend/memory": "./src/backend/memory.ts",
+    "./backend/sqlite": "./src/backend/sqlite.ts",
     "./errors": "./src/errors.ts",
     "./hash-file": "./src/hash-file.ts",
     "./objects": "./src/objects/index.ts",
     "./odb/file": "./src/odb/file.ts",
     "./odb/memory": "./src/odb/memory.ts",
+    "./odb/sqlite": "./src/odb/sqlite.ts",
     "./pack": "./src/pack/index.ts",
     "./refs/file": "./src/refs/file.ts",
     "./refs/memory": "./src/refs/memory.ts",
@@ -23,9 +25,13 @@
     "./refs/resolve": "./src/refs/resolve.ts",
     "./refs/shallow/file": "./src/refs/shallow/file.ts",
     "./refs/shallow/memory": "./src/refs/shallow/memory.ts",
+    "./refs/shallow/sqlite": "./src/refs/shallow/sqlite.ts",
+    "./refs/sqlite": "./src/refs/sqlite.ts",
+    "./remote/http": "./src/remote/http.ts",
     "./repository/core": "./src/repository/core.ts",
     "./repository/file": "./src/repository/file.ts",
     "./repository/memory": "./src/repository/memory.ts",
+    "./repository/sqlite": "./src/repository/sqlite.ts",
     "./repository/tree/tree-patch": "./src/repository/tree/tree-patch.ts",
     "./repository/tree/tree-walk": "./src/repository/tree/tree-walk.ts",
     "./sha1": "./src/sha1.ts",
@@ -42,11 +48,13 @@
       "./backend": "./dist/backend/index.mjs",
       "./backend/file": "./dist/backend/file.mjs",
       "./backend/memory": "./dist/backend/memory.mjs",
+      "./backend/sqlite": "./dist/backend/sqlite.mjs",
       "./errors": "./dist/errors.mjs",
       "./hash-file": "./dist/hash-file.mjs",
       "./objects": "./dist/objects/index.mjs",
       "./odb/file": "./dist/odb/file.mjs",
       "./odb/memory": "./dist/odb/memory.mjs",
+      "./odb/sqlite": "./dist/odb/sqlite.mjs",
       "./pack": "./dist/pack/index.mjs",
       "./refs/file": "./dist/refs/file.mjs",
       "./refs/memory": "./dist/refs/memory.mjs",
@@ -54,9 +62,13 @@
       "./refs/resolve": "./dist/refs/resolve.mjs",
       "./refs/shallow/file": "./dist/refs/shallow/file.mjs",
       "./refs/shallow/memory": "./dist/refs/shallow/memory.mjs",
+      "./refs/shallow/sqlite": "./dist/refs/shallow/sqlite.mjs",
+      "./refs/sqlite": "./dist/refs/sqlite.mjs",
+      "./remote/http": "./dist/remote/http.mjs",
       "./repository/core": "./dist/repository/core.mjs",
       "./repository/file": "./dist/repository/file.mjs",
       "./repository/memory": "./dist/repository/memory.mjs",
+      "./repository/sqlite": "./dist/repository/sqlite.mjs",
       "./repository/tree/tree-patch": "./dist/repository/tree/tree-patch.mjs",
       "./repository/tree/tree-walk": "./dist/repository/tree/tree-walk.mjs",
       "./sha1": "./dist/sha1.mjs",