@yydb/light-db 0.0.0 → 0.0.10

package/readme.md

@@ -1,124 +1,110 @@
-# LightDB Storage Engine 🚀
+# `@yydb/light-db`
 
-A high-performance TypeScript database storage layer with WAL (Write-Ahead Logging), indexes, and transaction support.
+**Light DB** is the browser edition of YYDB: a database written in pure TypeScript that stores `.yydb`-style
+snapshots, WAL records and checkpoints in browser storage. It has no Node built-ins, no N-API bindings and no WASM in
+its runtime path.
 
-## Features ✨
+## Product relationship
 
-- **High Performance**: Optimized for speed with batch writing and columnar storage
-- **Transaction Support**: ACID-compliant operations
-- **Indexing**: B+ tree indexes for fast querying
-- **Write-Ahead Logging**: Ensures data durability
-- **Recovery**: Automatic recovery from crashes
-- **Memory-Mapped Files**: Efficient I/O operations
-- **TypeScript Ready**: Full TypeScript support with type definitions
+| Package | Role |
+|---------|------|
+| `@yydb/yydb` | Node product: native Rust engine, N-API, local `.yydb` / `.yydx` files and CLI |
+| `@yydb/light-db` | Browser product: pure TypeScript, OPFS / IndexedDB storage, Web APIs, same author surface |
+| `@yydb/yydb-client` | Remote wire client for a running `yydb serve` |
 
-## Installation 📦
+## Status
 
-```bash
-pnpm add @yydb/light-db
-```
-
-## Quick Start 🚀
-
-```typescript
-import { LightDB } from '@yydb/light-db';
+Light DB is a migration of the original `LightDB.ts` engine, rebuilt around a browser-native architecture. The package
+ships as a pre-1.0 release of the browser product, so the author surface may still change between patch releases.
 
-// Initialize the database
-const db = await LightDB.open('./mydb');
+Current coverage:
 
-// Create a collection
-const users = db.collection('users');
+- `pnpm test` runs the Node-side runner over codec, adapter and database logic (29 cases).
+- `pnpm test:browser` runs the conformance suite in an installed Chrome (16 cases): OPFS persistence across reopen, WAL
+  recovery, checkpoint truncation, corruption detection, single-writer exclusion, transaction rollback and commit,
+  schema and close notifications, and two-tab lease and broadcast behaviour.
 
-// Insert a document
-await users.insert({ id: 1, name: 'John Doe', email: 'john@example.com' });
+## Usage
 
-// Find a document
-const user = await users.findOne({ id: 1 });
-console.log(user); // { id: 1, name: 'John Doe', email: 'john@example.com' }
+```ts
+import { LightDbError, openLightDatabase } from '@yydb/light-db';
 
-// Update a document
-await users.update({ id: 1 }, { $set: { name: 'John Smith' } });
+const db = await openLightDatabase('app');
 
-// Delete a document
-await users.delete({ id: 1 });
+await db.ensureSchema('// @yydb-schema-version: 1\nkv users');
+await db.put('user:1', new TextEncoder().encode('Ada'));
 
-// Close the database
+const value = await db.get('user:1');
+await db.checkpoint();
 await db.close();
 ```
 
-## API Reference 📚
-
-### LightDB Class
-
-#### `open(path: string): Promise<LightDB>`
-Opens an existing database or creates a new one at the specified path.
-
-#### `collection(name: string): Collection`
-Returns a collection with the given name. Creates it if it doesn't exist.
-
-#### `transaction(): Promise<Transaction>`
-Starts a new transaction.
-
-#### `close(): Promise<void>`
-Closes the database connection.
-
-### Collection Class
+Public data types are browser-native: keys and values use `Uint8Array`, databases are addressed by name rather than by
+file path, and every lifecycle call is asynchronous.
 
-#### `insert(document: Document): Promise<void>`
-Inserts a new document into the collection.
+## Author surface
 
-#### `find(query: Query): Promise<Document[]>`
-Finds all documents matching the query.
+```ts
+const db: LightDatabase = await openLightDatabase('app', options);
 
-#### `findOne(query: Query): Promise<Document | null>`
-Finds the first document matching the query.
-
-#### `update(query: Query, update: Update): Promise<number>`
-Updates documents matching the query and returns the number of updated documents.
-
-#### `delete(query: Query): Promise<number>`
-Deletes documents matching the query and returns the number of deleted documents.
-
-#### `createIndex(field: string): Promise<void>`
-Creates an index on the specified field for faster queries.
-
-### Transaction Class
-
-#### `commit(): Promise<void>`
-Commits the transaction.
-
-#### `rollback(): Promise<void>`
-Rolls back the transaction.
-
-## Performance Features ⚡
+await db.schema();
+await db.ensureSchema(document);
+await db.get(key);
+await db.put(key, value);
+await db.delete(key);
+await db.begin();
+await db.commit();
+await db.rollback();
+await db.checkpoint();
+db.stats();
+await db.close();
+```
 
-### Batch Writing
-LightDB uses batch writing to optimize disk I/O operations, significantly improving write performance for bulk operations.
+`schema()` returns the persisted schema version and document. The document is the single source of truth: a second
+`ensureSchema` call must pass the identical document, otherwise it fails with `yydb.schema.conflict`. Keys starting with
+`__yydb__/` are reserved for the database.
 
-### Columnar Storage
-For certain data types, LightDB uses columnar storage to reduce disk space and improve query performance.
+## Storage backends
 
-### Memory-Mapped Files
-LightDB uses memory-mapped files for efficient I/O operations, reducing the overhead of traditional file I/O.
+| Adapter | Use |
+|---------|-----|
+| `OpfsStorageAdapterFactory` | Default. Origin Private File System, positional reads and writes, atomic snapshot publication |
+| `IndexedDbStorageAdapterFactory` | Compatibility backend for hosts without OPFS |
+| `MemoryStorageBackend` | Tests and throwaway sessions |
 
-## Architecture 🏗️
+`StorageAdapter` is the only platform boundary. Transactions, recovery and checkpoint semantics live in `core`, so
+backends implement files, not database behaviour.
 
-LightDB consists of several key components:
+## Concurrency
 
-1. **Storage Engine**: Manages the physical storage of data
-2. **WAL (Write-Ahead Log)**: Ensures data durability and supports recovery
-3. **Index Manager**: Manages B+ tree indexes for fast querying
-4. **Collection Layer**: Provides a document-oriented API
-5. **Transaction Manager**: Handles ACID-compliant transactions
+A writer holds a session-scoped `Web Locks` lease. A second tab that opens the same database fails with
+`yydb.lease.unavailable` and `retryable: true` instead of silently writing alongside the first one. When a lock manager
+is missing the call fails the same way; it never degrades to multiple writers.
 
-## Recovery 🔄
+`BroadcastChannel` carries `commit`, `schema` and `close` events so other same-origin contexts can discard stale views
+and retry after the lease is released. `listenDatabaseEvents(name, handler)` subscribes without opening the database.
 
-LightDB automatically recovers from crashes using the WAL. When the database is opened after a crash, it replays the WAL to restore the database to a consistent state.
+## Layout
 
-## Contributing 🤝
+| Path | Role |
+|------|------|
+| `src/api/` | Public database, transaction, schema and shared types |
+| `src/core/` | Records, WAL, checkpoint, recovery, writer lease and broadcast |
+| `src/storage/` | `StorageAdapter` plus OPFS, IndexedDB and memory backends |
+| `src/codec/` | Page, snapshot and WAL record encoding over `Uint8Array` |
+| `src/errors/` | Stable `yydb.*` error codes |
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## Errors
 
-## License 📄
+| Code | Meaning |
+|------|---------|
+| `yydb.io` | Storage operation failed |
+| `yydb.corrupt` | Persisted bytes failed validation |
+| `yydb.schema.conflict` | Schema document differs from the stored one |
+| `yydb.schema.invalid` | Schema document is not usable |
+| `yydb.unsupported` | Host or operation is not supported |
+| `yydb.session.closed` | Database or handle is closed |
+| `yydb.lease.unavailable` | Writer lease is held elsewhere or Web Locks is missing (retryable) |
+| `yydb.quota.exceeded` | Browser storage quota is exhausted |
 
-LightDB is licensed under the MPL-2.0 License. See the [LICENSE](LICENSE) file for details.
+[YYDB overview](https://github.com/yy-database/yydb.rs)

package/dist/api/LightDB.d.ts

@@ -1,194 +0,0 @@
-/**
- * LightDB 主类
- * 提供用户直接使用的接口层
- */
-import { StorageEngine } from "../storage";
-import { Collection } from "../collection";
-import type {
-    LightDBOptions,
-    CollectionCreateOptions,
-    TransactionCallback,
-    TransactionOptions,
-    TransactionResult,
-    DatabaseStats,
-    DatabaseConfig,
-    ILightDB,
-    CollectionSchema,
-} from "./types";
-import type { CheckpointResult } from "../types";
-/**
- * LightDB 数据库实例
- * 提供完整的数据库操作 API
- */
-export declare class LightDB implements ILightDB {
-    private readonly storageEngine;
-    private readonly collections;
-    private readonly transactionManager;
-    private readonly options;
-    private closed;
-    /**
-     * 创建 LightDB 实例
-     * @param storageEngine 已初始化的存储引擎
-     * @param options 配置选项
-     */
-    private constructor();
-    /**
-     * 打开数据库
-     * 创建或打开指定路径的数据库
-     *
-     * @param path 数据库文件存储路径
-     * @param options 配置选项
-     * @returns 初始化完成的 LightDB 实例
-     *
-     * @example
-     * ```typescript
-     * const db = await LightDB.open('./data/mydb', {
-     *   dbName: 'mydb',
-     *   autoCheckpoint: true,
-     *   pageSize: 4096
-     * });
-     * ```
-     */
-    static open(path: string, options?: LightDBOptions): Promise<LightDB>;
-    /**
-     * 获取数据库名称
-     */
-    get dbName(): string;
-    /**
-     * 获取数据库路径
-     */
-    get path(): string;
-    /**
-     * 检查数据库是否已打开
-     */
-    get isOpen(): boolean;
-    /**
-     * 获取或创建集合
-     * 返回类型安全的集合实例
-     *
-     * @param name 集合名称
-     * @param options 集合配置选项
-     * @returns 集合实例
-     *
-     * @example
-     * ```typescript
-     * interface User {
-     *   id: number;
-     *   name: string;
-     *   age: number;
-     * }
-     *
-     * const users = db.collection<User>('users', {
-     *   name: 'users',
-     *   primaryKey: 'id',
-     *   indexes: [
-     *     { name: 'name_idx', fieldName: 'name' }
-     *   ]
-     * });
-     * ```
-     */
-    collection<T extends Record<string, unknown>>(name: string, options: CollectionCreateOptions<T>): Collection<T>;
-    /**
-     * 检查集合是否存在
-     *
-     * @param name 集合名称
-     * @returns 集合是否存在
-     */
-    hasCollection(name: string): boolean;
-    /**
-     * 删除集合
-     *
-     * @param name 集合名称
-     * @returns 是否删除成功
-     */
-    dropCollection(name: string): boolean;
-    /**
-     * 获取所有集合名称
-     *
-     * @returns 集合名称数组
-     */
-    getCollectionNames(): string[];
-    /**
-     * 执行事务
-     * 支持 ACID 事务特性
-     *
-     * @param callback 事务回调函数
-     * @param options 事务选项
-     * @returns 事务执行结果
-     *
-     * @example
-     * ```typescript
-     * await db.transaction(async (tx) => {
-     *   const users = tx.collection<User>('users');
-     *   const user = await users.findOne({ id: 1 });
-     *   await users.update({ id: 1 }, { balance: user.balance - 100 });
-     * });
-     * ```
-     */
-    transaction(callback: TransactionCallback, options?: TransactionOptions): Promise<TransactionResult>;
-    /**
-     * 执行检查点
-     * 将内存中的数据持久化到磁盘
-     *
-     * @returns 检查点执行结果
-     */
-    checkpoint(): Promise<CheckpointResult>;
-    /**
-     * 获取数据库统计信息
-     *
-     * @returns 数据库统计信息
-     */
-    getStats(): Promise<DatabaseStats>;
-    /**
-     * 获取数据库配置
-     *
-     * @returns 数据库配置信息
-     */
-    getConfig(): DatabaseConfig;
-    /**
-     * 同步数据到磁盘
-     * 确保所有数据都已持久化
-     */
-    sync(): Promise<void>;
-    /**
-     * 关闭数据库
-     * 释放所有资源并确保数据持久化
-     */
-    close(): Promise<void>;
-    /**
-     * 确保数据库处于打开状态
-     */
-    private ensureOpen;
-    /**
-     * 获取存储引擎（内部使用）
-     */
-    getStorageEngine(): StorageEngine;
-}
-/**
- * 定义集合 Schema 的辅助函数
- * 提供类型推断和 IDE 支持
- *
- * @param schema Schema 定义
- * @returns Schema 对象
- *
- * @example
- * ```typescript
- * const UserSchema = defineCollectionSchema({
- *   schema: {} as User,
- *   primaryKey: 'id',
- *   indexes: [
- *     { name: 'name_idx', fieldName: 'name' }
- *   ]
- * });
- * ```
- */
-export declare function defineCollectionSchema<T extends Record<string, unknown>>(schema: CollectionSchema<T>): CollectionSchema<T>;
-/**
- * 打开数据库的便捷函数
- *
- * @param path 数据库文件存储路径
- * @param options 配置选项
- * @returns 初始化完成的 LightDB 实例
- */
-export declare function openDatabase(path: string, options?: LightDBOptions): Promise<LightDB>;
-//# sourceMappingURL=LightDB.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"LightDB.d.ts","sourceRoot":"","sources":["../../src/api/LightDB.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAuB,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,OAAO,KAAK,EACR,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,QAAQ,EACR,gBAAgB,EACnB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,gBAAgB,EAAsC,MAAM,UAAU,CAAC;AAGrF;;;GAGG;AACH,qBAAa,OAAQ,YAAW,QAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmD;IAC/E,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAEtB;IACF,OAAO,CAAC,MAAM,CAAU;IAExB;;;;OAIG;IACH,OAAO;IAaP;;;;;;;;;;;;;;;;OAgBG;WACiB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBtF;;OAEG;IACH,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAW,MAAM,IAAI,OAAO,CAE3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAoBtH;;;;;OAKG;IACI,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK3C;;;;;OAKG;IACI,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAa5C;;;;OAIG;IACI,kBAAkB,IAAI,MAAM,EAAE;IAKrC;;;;;;;;;;;;;;;;OAgBG;IACU,WAAW,CAAC,QAAQ,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKjH;;;;;OAKG;IACU,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAKpD;;;;OAIG;IACU,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC;IAmB/C;;;;OAIG;IACI,SAAS,IAAI,cAAc;IAUlC;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAcnC;;OAEG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACI,gBAAgB,IAAI,aAAa;CAG3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAE1H;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3F"}