@yydb/light-db 0.0.0 → 0.0.11

package/dist/api/database.d.ts

@@ -0,0 +1,48 @@
+import { type EmittableItem } from '@voml/vos';
+/** Schema 版本与文档。 */
+export interface SchemaVersion {
+    version: number;
+    document: string;
+}
+/** 打开浏览器数据库的选项。 */
+export interface LightDatabaseOptions {
+    /** 使用内存 session（测试专用；默认使用 OPFS 持久 session）。 */
+    memory?: boolean;
+}
+/** 浏览器侧 YYDB 数据库句柄，委托给 Rust WASM 核心。 */
+export declare class BrowserDatabase {
+    /** 数据库名（OPFS 路径）。 */
+    readonly name: string;
+    private readonly session;
+    private constructor();
+    /** 初始化 WASM 并打开一个 session（memory 或 OPFS persistent）。 */
+    static open(name: string, options?: LightDatabaseOptions): Promise<BrowserDatabase>;
+    /** 读取已持久化的 schema，或 `null`。 */
+    schema(): Promise<SchemaVersion | null>;
+    /**
+     * 声明 schema 文档。接受原始 `.vos` 源码字符串，或 `@voml/vos`
+     * descriptor（`v.table()` / `v.class()`），或多个 descriptor。
+     */
+    ensureSchema(...input: [string] | EmittableItem[]): Promise<void>;
+    /** 读取键，或 `null`。 */
+    get(key: string): Promise<Uint8Array | null>;
+    /** 写入键。 */
+    put(key: string, value: Uint8Array): Promise<void>;
+    /** 删除键（底层等价 write_batch([(key, None)])）。 */
+    delete(key: string): Promise<boolean>;
+    /** 开启事务。 */
+    begin(): Promise<void>;
+    /** 提交事务。 */
+    commit(): Promise<void>;
+    /** 回滚事务。 */
+    rollback(): Promise<void>;
+    /** 执行检查点（折叠 WAL）。 */
+    checkpoint(): Promise<void>;
+    /** 数据库统计（暂不可用）。 */
+    stats(): never;
+    /** 关闭 session。 */
+    close(): Promise<void>;
+}
+/** 打开浏览器数据库的便捷函数。 */
+export declare function openLightDatabase(name: string, options?: LightDatabaseOptions): Promise<BrowserDatabase>;
+//# sourceMappingURL=database.d.ts.map

package/dist/api/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/api/database.ts"],"names":[],"mappings":"AAMA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAY3D,oBAAoB;AACpB,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,mBAAmB;AACnB,MAAM,WAAW,oBAAoB;IACjC,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAWD,wCAAwC;AACxC,qBAAa,eAAe;IACxB,qBAAqB;IACrB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAE1C,OAAO;IAKP,wDAAwD;WACpC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,eAAe,CAAC;IAcpG,+BAA+B;IAClB,MAAM,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAWpD;;;OAGG;IACU,YAAY,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9E,oBAAoB;IACP,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAmBzD,WAAW;IACE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/D,4CAA4C;IAC/B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQlD,YAAY;IACC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnC,YAAY;IACC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC,YAAY;IACC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtC,qBAAqB;IACR,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxC,mBAAmB;IACZ,KAAK,IAAI,KAAK;IAIrB,kBAAkB;IACL,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGtC;AAED,qBAAqB;AACrB,wBAAsB,iBAAiB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GACnC,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/dist/api/database.js

@@ -0,0 +1,120 @@
+import { initWasm, openPersistentSession, createMemorySession, } from '@yydb/yydb-unknown-wasm32';
+import { emitSource } from '@voml/vos';
+/** 浏览器侧 YYDB 数据库句柄，委托给 Rust WASM 核心。 */
+export class BrowserDatabase {
+    /** 数据库名（OPFS 路径）。 */
+    name;
+    session;
+    constructor(name, session) {
+        this.name = name;
+        this.session = session;
+    }
+    /** 初始化 WASM 并打开一个 session（memory 或 OPFS persistent）。 */
+    static async open(name, options = {}) {
+        if (!name || name.length === 0) {
+            throw new Error('database name must not be empty');
+        }
+        await initWasm();
+        const base = options.memory
+            ? createMemorySession()
+            : openPersistentSession(name);
+        return new BrowserDatabase(name, base);
+    }
+    /** 读取已持久化的 schema，或 `null`。 */
+    async schema() {
+        const raw = JSON.parse(this.session.getSchema());
+        if (!raw.ok) {
+            throw new Error(raw.error ?? 'getSchema failed');
+        }
+        if (!raw.schema) {
+            return null;
+        }
+        return raw.schema;
+    }
+    /**
+     * 声明 schema 文档。接受原始 `.vos` 源码字符串，或 `@voml/vos`
+     * descriptor（`v.table()` / `v.class()`），或多个 descriptor。
+     */
+    async ensureSchema(...input) {
+        const document = typeof input[0] === 'string' ? input[0] : emitSource(input);
+        const raw = JSON.parse(this.session.ensureSchema(document));
+        if (!raw.ok) {
+            throw new Error(raw.error ?? 'ensureSchema failed');
+        }
+    }
+    /** 读取键，或 `null`。 */
+    async get(key) {
+        const raw = JSON.parse(this.session.get(key));
+        if (!raw.ok) {
+            throw new Error(raw.error ?? `get(${key}) failed`);
+        }
+        if (raw.value === null || raw.value === undefined) {
+            return null;
+        }
+        // WASM JSON 序列化为普通数组 [1, 2, 3, ...]；转回 Uint8Array
+        if (raw.value instanceof Uint8Array) {
+            return raw.value;
+        }
+        if (Array.isArray(raw.value)) {
+            return new Uint8Array(raw.value);
+        }
+        // 兜底：如果是 base64 字符串等，尝试 new Uint8Array
+        return new Uint8Array(raw.value);
+    }
+    /** 写入键。 */
+    async put(key, value) {
+        const raw = JSON.parse(this.session.put(key, value));
+        if (!raw.ok) {
+            throw new Error(raw.error ?? `put(${key}) failed`);
+        }
+    }
+    /** 删除键（底层等价 write_batch([(key, None)])）。 */
+    async delete(key) {
+        const raw = JSON.parse(this.session.delete(key));
+        if (!raw.ok) {
+            throw new Error(raw.error ?? `delete(${key}) failed`);
+        }
+        return true;
+    }
+    /** 开启事务。 */
+    async begin() {
+        const raw = JSON.parse(this.session.begin());
+        if (!raw.ok) {
+            throw new Error(raw.error ?? 'begin failed');
+        }
+    }
+    /** 提交事务。 */
+    async commit() {
+        const raw = JSON.parse(this.session.commit());
+        if (!raw.ok) {
+            throw new Error(raw.error ?? 'commit failed');
+        }
+    }
+    /** 回滚事务。 */
+    async rollback() {
+        const raw = JSON.parse(this.session.rollback());
+        if (!raw.ok) {
+            throw new Error(raw.error ?? 'rollback failed');
+        }
+    }
+    /** 执行检查点（折叠 WAL）。 */
+    async checkpoint() {
+        const raw = JSON.parse(this.session.checkpoint());
+        if (!raw.ok) {
+            throw new Error(raw.error ?? 'checkpoint failed');
+        }
+    }
+    /** 数据库统计（暂不可用）。 */
+    stats() {
+        throw new Error('stats() is not available on the WASM core');
+    }
+    /** 关闭 session。 */
+    async close() {
+        this.session.close();
+    }
+}
+/** 打开浏览器数据库的便捷函数。 */
+export async function openLightDatabase(name, options = {}) {
+    return BrowserDatabase.open(name, options);
+}
+//# sourceMappingURL=database.js.map

package/dist/api/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/api/database.ts"],"names":[],"mappings":"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"}

package/dist/api/index.d.ts

@@ -1,24 +1,9 @@
 /**
- * LightDB API 层
- * 提供用户直接使用的接口层
- *
- * @packageDocumentation
+ * api 层导出
  */
-export {
-    LightDBOptions,
-    CollectionCreateOptions,
-    TransactionContext,
-    TransactionCollection,
-    TransactionCallback,
-    TransactionOptions,
-    TransactionState,
-    TransactionResult,
-    DatabaseStats,
-    DatabaseConfig,
-    ILightDB,
-    DefineCollectionSchema,
-    CollectionSchema,
-} from "./types";
-export { TransactionError, Transaction, TransactionManager } from "./Transaction";
-export { LightDB, defineCollectionSchema, openDatabase } from "./LightDB";
-//# sourceMappingURL=index.d.ts.map
+export { BrowserDatabase, openLightDatabase } from './database';
+export { Transaction } from './transaction';
+export type { TransactionState } from './transaction';
+export { SCHEMA_KEY, RESERVED_KEY_PREFIX, documentVersion, parseSchemaDocument, encodeSchema, decodeSchema } from './schema';
+export type { LightDatabase, LightDatabaseOptions, SchemaVersion } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,cAAc,EACd,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,gBAAgB,GACnB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACH,gBAAgB,EAChB,WAAW,EACX,kBAAkB,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7H,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/api/index.js

@@ -1,54 +1,7 @@
-"use strict";
 /**
- * LightDB API 层
- * 提供用户直接使用的接口层
- *
- * @packageDocumentation
+ * api 层导出
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.openDatabase =
-    exports.defineCollectionSchema =
-    exports.LightDB =
-    exports.TransactionManager =
-    exports.Transaction =
-    exports.TransactionError =
-        void 0;
-var Transaction_1 = require("./Transaction");
-Object.defineProperty(exports, "TransactionError", {
-    enumerable: true,
-    get: function () {
-        return Transaction_1.TransactionError;
-    },
-});
-Object.defineProperty(exports, "Transaction", {
-    enumerable: true,
-    get: function () {
-        return Transaction_1.Transaction;
-    },
-});
-Object.defineProperty(exports, "TransactionManager", {
-    enumerable: true,
-    get: function () {
-        return Transaction_1.TransactionManager;
-    },
-});
-var LightDB_1 = require("./LightDB");
-Object.defineProperty(exports, "LightDB", {
-    enumerable: true,
-    get: function () {
-        return LightDB_1.LightDB;
-    },
-});
-Object.defineProperty(exports, "defineCollectionSchema", {
-    enumerable: true,
-    get: function () {
-        return LightDB_1.defineCollectionSchema;
-    },
-});
-Object.defineProperty(exports, "openDatabase", {
-    enumerable: true,
-    get: function () {
-        return LightDB_1.openDatabase;
-    },
-});
-//# sourceMappingURL=index.js.map
+export { BrowserDatabase, openLightDatabase } from './database';
+export { Transaction } from './transaction';
+export { SCHEMA_KEY, RESERVED_KEY_PREFIX, documentVersion, parseSchemaDocument, encodeSchema, decodeSchema } from './schema';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAkBH,6CAIuB;AAHnB,+GAAA,gBAAgB,OAAA;AAChB,0GAAA,WAAW,OAAA;AACX,iHAAA,kBAAkB,OAAA;AAGtB,qCAA0E;AAAjE,kGAAA,OAAO,OAAA;AAAE,iHAAA,sBAAsB,OAAA;AAAE,uGAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/api/schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Schema 语义
+ *
+ * 与 `@yydb/yydb` 的 Rust 实现同构：Schema 文档是唯一真相，
+ * 版本由文档前导注释 `// @yydb-schema-version: <n>` 决定，默认 1。
+ */
+import type { SchemaVersion } from './types';
+/** Schema 记录在数据库中的保留键 */
+export declare const SCHEMA_KEY = "__yydb__/schema";
+/** 用户键禁止使用的内部前缀 */
+export declare const RESERVED_KEY_PREFIX = "__yydb__/";
+/**
+ * 从文档中提取版本
+ * @param document Schema 文档
+ */
+export declare function documentVersion(document: string): number;
+/**
+ * 校验 Schema 文档
+ * @param document Schema 文档
+ * @returns 文档声明的版本
+ */
+export declare function parseSchemaDocument(document: string): number;
+/**
+ * 编码 Schema 记录
+ * @param schema Schema 版本与文档
+ */
+export declare function encodeSchema(schema: SchemaVersion): Uint8Array;
+/**
+ * 解码 Schema 记录
+ * @param value 记录值
+ */
+export declare function decodeSchema(value: Uint8Array): SchemaVersion;
+//# sourceMappingURL=schema.d.ts.map

package/dist/api/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/api/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,yBAAyB;AACzB,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C,mBAAmB;AACnB,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAK/C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAE9D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAkB7D"}

package/dist/api/schema.js

@@ -0,0 +1,80 @@
+/**
+ * Schema 语义
+ *
+ * 与 `@yydb/yydb` 的 Rust 实现同构：Schema 文档是唯一真相，
+ * 版本由文档前导注释 `// @yydb-schema-version: <n>` 决定，默认 1。
+ */
+import { BinaryUtils } from '../codec';
+import { LightDbError, LightDbErrorCodes } from '../errors';
+/** Schema 记录在数据库中的保留键 */
+export const SCHEMA_KEY = '__yydb__/schema';
+/** 用户键禁止使用的内部前缀 */
+export const RESERVED_KEY_PREFIX = '__yydb__/';
+/** 版本声明注释 */
+const VERSION_PRAGMA = /^\s*\/\/\s*@yydb-schema-version:\s*(\d+)\s*$/m;
+/**
+ * 从文档中提取版本
+ * @param document Schema 文档
+ */
+export function documentVersion(document) {
+    const match = VERSION_PRAGMA.exec(document);
+    if (!match) {
+        return 1;
+    }
+    const version = Number.parseInt(match[1], 10);
+    return Number.isFinite(version) && version > 0 ? version : 1;
+}
+/**
+ * 校验 Schema 文档
+ * @param document Schema 文档
+ * @returns 文档声明的版本
+ */
+export function parseSchemaDocument(document) {
+    if (document.trim().length === 0) {
+        throw new LightDbError(LightDbErrorCodes.schemaInvalid, 'schema document must not be empty', {
+            operation: 'ensureSchema',
+        });
+    }
+    return documentVersion(document);
+}
+/**
+ * 编码 Schema 记录
+ * @param schema Schema 版本与文档
+ */
+export function encodeSchema(schema) {
+    return BinaryUtils.encode(JSON.stringify(schema));
+}
+/**
+ * 解码 Schema 记录
+ * @param value 记录值
+ */
+export function decodeSchema(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(BinaryUtils.decode(value));
+    }
+    catch (error) {
+        throw new LightDbError(LightDbErrorCodes.corrupt, 'persisted schema record is not valid JSON', {
+            operation: 'schema',
+            cause: error,
+        });
+    }
+    if (!isSchemaVersion(parsed)) {
+        throw new LightDbError(LightDbErrorCodes.corrupt, 'persisted schema record has an unexpected shape', {
+            operation: 'schema',
+        });
+    }
+    return parsed;
+}
+/**
+ * 判断值是否为 Schema 记录
+ * @param value 待判断值
+ */
+function isSchemaVersion(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const record = value;
+    return typeof record.version === 'number' && typeof record.document === 'string';
+}
+//# sourceMappingURL=schema.js.map

package/dist/api/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/api/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG5D,yBAAyB;AACzB,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAE5C,mBAAmB;AACnB,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAE/C,aAAa;AACb,MAAM,cAAc,GAAG,+CAA+C,CAAC;AAEvE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC5C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,OAAO,CAAC,CAAC;IACb,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAChD,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,aAAa,EAAE,mCAAmC,EAAE;YACzF,SAAS,EAAE,cAAc;SAC5B,CAAC,CAAC;IACP,CAAC;IACD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAC9C,OAAO,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC1C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,OAAO,EAAE,2CAA2C,EAAE;YAC3F,SAAS,EAAE,QAAQ;YACnB,KAAK,EAAE,KAAK;SACf,CAAC,CAAC;IACP,CAAC;IAED,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,OAAO,EAAE,iDAAiD,EAAE;YACjG,SAAS,EAAE,QAAQ;SACtB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,KAAkD,CAAC;IAClE,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACrF,CAAC"}

package/dist/api/transaction.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 事务作者面
+ *
+ * 事务语义由 `core/engine` 维护，本层只提供异步调用形态与状态跟踪。
+ */
+import type { StorageEngine } from '../core/engine';
+export type { TransactionState } from '../core/engine';
+/**
+ * 事务句柄
+ *
+ * 一个数据库同时只允许一个写事务；重复开始会得到 `yydb.unsupported`。
+ */
+export declare class Transaction {
+    private readonly engine;
+    private active;
+    constructor(engine: StorageEngine);
+    /** 是否处于事务中 */
+    get isActive(): boolean;
+    /** 开始事务 */
+    begin(): Promise<void>;
+    /** 提交事务，失败时事务仍视为结束 */
+    commit(): Promise<void>;
+    /** 回滚事务 */
+    rollback(): Promise<void>;
+}
+//# sourceMappingURL=transaction.d.ts.map

package/dist/api/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/api/transaction.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;GAIG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,aAAa;IAIjC,cAAc;IACd,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,WAAW;IACE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnC,sBAAsB;IACT,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAYpC,WAAW;IACE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAWzC"}

package/dist/api/transaction.js

@@ -0,0 +1,52 @@
+/**
+ * 事务作者面
+ *
+ * 事务语义由 `core/engine` 维护，本层只提供异步调用形态与状态跟踪。
+ */
+import { LightDbError, LightDbErrorCodes } from '../errors';
+/**
+ * 事务句柄
+ *
+ * 一个数据库同时只允许一个写事务；重复开始会得到 `yydb.unsupported`。
+ */
+export class Transaction {
+    engine;
+    active = false;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    /** 是否处于事务中 */
+    get isActive() {
+        return this.active;
+    }
+    /** 开始事务 */
+    async begin() {
+        this.engine.begin();
+        this.active = true;
+    }
+    /** 提交事务，失败时事务仍视为结束 */
+    async commit() {
+        if (!this.active) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'no active transaction', { operation: 'commit' });
+        }
+        try {
+            await this.engine.commit();
+        }
+        finally {
+            this.active = false;
+        }
+    }
+    /** 回滚事务 */
+    async rollback() {
+        if (!this.active) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'no active transaction', { operation: 'rollback' });
+        }
+        try {
+            this.engine.rollback();
+        }
+        finally {
+            this.active = false;
+        }
+    }
+}
+//# sourceMappingURL=transaction.js.map

package/dist/api/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/api/transaction.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAI5D;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACH,MAAM,CAAgB;IAC/B,MAAM,GAAY,KAAK,CAAC;IAEhC,YAAY,MAAqB;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,cAAc;IACd,IAAW,QAAQ;QACf,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,WAAW;IACJ,KAAK,CAAC,KAAK;QACd,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,sBAAsB;IACf,KAAK,CAAC,MAAM;QACf,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACf,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,WAAW,EAAE,uBAAuB,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5G,CAAC;QAED,IAAI,CAAC;YACD,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/B,CAAC;gBAAS,CAAC;YACP,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACxB,CAAC;IACL,CAAC;IAED,WAAW;IACJ,KAAK,CAAC,QAAQ;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACf,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,WAAW,EAAE,uBAAuB,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;QAC9G,CAAC;QAED,IAAI,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC3B,CAAC;gBAAS,CAAC;YACP,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACxB,CAAC;IACL,CAAC;CACJ"}