@yydb/light-db 0.0.0

package/dist/storage/index.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * 存储模块导出
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStorageEngine =
+    exports.StorageEngine =
+    exports.RecoveryPhase =
+    exports.RecoveryValidator =
+    exports.FastRecoveryManager =
+    exports.RecoveryManager =
+    exports.IncrementalCheckpointManager =
+    exports.AutoCheckpointScheduler =
+    exports.CheckpointManager =
+    exports.WalIndexManager =
+    exports.ShmFileManager =
+    exports.ShmHashTable =
+    exports.ShmSerializer =
+    exports.WalManager =
+    exports.WalReader =
+    exports.WalWriter =
+    exports.WalRecordSerializer =
+    exports.PageManager =
+    exports.LightFileManager =
+    exports.LightFileSerializer =
+        void 0;
+var LightFile_1 = require("./LightFile");
+Object.defineProperty(exports, "LightFileSerializer", {
+    enumerable: true,
+    get: function () {
+        return LightFile_1.LightFileSerializer;
+    },
+});
+Object.defineProperty(exports, "LightFileManager", {
+    enumerable: true,
+    get: function () {
+        return LightFile_1.LightFileManager;
+    },
+});
+Object.defineProperty(exports, "PageManager", {
+    enumerable: true,
+    get: function () {
+        return LightFile_1.PageManager;
+    },
+});
+var WALFile_1 = require("./WALFile");
+Object.defineProperty(exports, "WalRecordSerializer", {
+    enumerable: true,
+    get: function () {
+        return WALFile_1.WalRecordSerializer;
+    },
+});
+Object.defineProperty(exports, "WalWriter", {
+    enumerable: true,
+    get: function () {
+        return WALFile_1.WalWriter;
+    },
+});
+Object.defineProperty(exports, "WalReader", {
+    enumerable: true,
+    get: function () {
+        return WALFile_1.WalReader;
+    },
+});
+Object.defineProperty(exports, "WalManager", {
+    enumerable: true,
+    get: function () {
+        return WALFile_1.WalManager;
+    },
+});
+var SHMFile_1 = require("./SHMFile");
+Object.defineProperty(exports, "ShmSerializer", {
+    enumerable: true,
+    get: function () {
+        return SHMFile_1.ShmSerializer;
+    },
+});
+Object.defineProperty(exports, "ShmHashTable", {
+    enumerable: true,
+    get: function () {
+        return SHMFile_1.ShmHashTable;
+    },
+});
+Object.defineProperty(exports, "ShmFileManager", {
+    enumerable: true,
+    get: function () {
+        return SHMFile_1.ShmFileManager;
+    },
+});
+Object.defineProperty(exports, "WalIndexManager", {
+    enumerable: true,
+    get: function () {
+        return SHMFile_1.WalIndexManager;
+    },
+});
+var Checkpoint_1 = require("./Checkpoint");
+Object.defineProperty(exports, "CheckpointManager", {
+    enumerable: true,
+    get: function () {
+        return Checkpoint_1.CheckpointManager;
+    },
+});
+Object.defineProperty(exports, "AutoCheckpointScheduler", {
+    enumerable: true,
+    get: function () {
+        return Checkpoint_1.AutoCheckpointScheduler;
+    },
+});
+Object.defineProperty(exports, "IncrementalCheckpointManager", {
+    enumerable: true,
+    get: function () {
+        return Checkpoint_1.IncrementalCheckpointManager;
+    },
+});
+var Recovery_1 = require("./Recovery");
+Object.defineProperty(exports, "RecoveryManager", {
+    enumerable: true,
+    get: function () {
+        return Recovery_1.RecoveryManager;
+    },
+});
+Object.defineProperty(exports, "FastRecoveryManager", {
+    enumerable: true,
+    get: function () {
+        return Recovery_1.FastRecoveryManager;
+    },
+});
+Object.defineProperty(exports, "RecoveryValidator", {
+    enumerable: true,
+    get: function () {
+        return Recovery_1.RecoveryValidator;
+    },
+});
+Object.defineProperty(exports, "RecoveryPhase", {
+    enumerable: true,
+    get: function () {
+        return Recovery_1.RecoveryPhase;
+    },
+});
+var StorageEngine_1 = require("./StorageEngine");
+Object.defineProperty(exports, "StorageEngine", {
+    enumerable: true,
+    get: function () {
+        return StorageEngine_1.StorageEngine;
+    },
+});
+Object.defineProperty(exports, "createStorageEngine", {
+    enumerable: true,
+    get: function () {
+        return StorageEngine_1.createStorageEngine;
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,yCAIqB;AAHjB,gHAAA,mBAAmB,OAAA;AACnB,6GAAA,gBAAgB,OAAA;AAChB,wGAAA,WAAW,OAAA;AAEf,qCAKmB;AAJf,8GAAA,mBAAmB,OAAA;AACnB,oGAAA,SAAS,OAAA;AACT,oGAAA,SAAS,OAAA;AACT,qGAAA,UAAU,OAAA;AAEd,qCAKmB;AAJf,wGAAA,aAAa,OAAA;AACb,uGAAA,YAAY,OAAA;AACZ,yGAAA,cAAc,OAAA;AACd,0GAAA,eAAe,OAAA;AAEnB,2CAKsB;AAJlB,+GAAA,iBAAiB,OAAA;AACjB,qHAAA,uBAAuB,OAAA;AACvB,0HAAA,4BAA4B,OAAA;AAGhC,uCAMoB;AALhB,2GAAA,eAAe,OAAA;AACf,+GAAA,mBAAmB,OAAA;AACnB,6GAAA,iBAAiB,OAAA;AACjB,yGAAA,aAAa,OAAA;AAGjB,iDAAqE;AAA5D,8GAAA,aAAa,OAAA;AAAE,oHAAA,mBAAmB,OAAA"}

package/dist/types/index.d.ts

@@ -0,0 +1,220 @@
+/**
+ * LightDB 存储引擎类型定义
+ * 包含所有公共接口、类型和结构体定义
+ */
+import { OperationType } from "../constants";
+/**
+ * .light 文件头部结构
+ * 存储文件元信息和全局状态
+ */
+export interface LightHeader {
+    /** 魔数：用于验证文件格式 */
+    magic: number;
+    /** 文件格式版本号 */
+    version: number;
+    /** 页面大小（字节） */
+    pageSize: number;
+    /** 上次快照时的 LSN */
+    lastSnapshotLsn: bigint;
+}
+/**
+ * 数据记录结构
+ * 表示存储在页面中的单条记录
+ */
+export interface Record {
+    /** 记录键 */
+    key: string;
+    /** 记录值（序列化后的二进制数据） */
+    value: Buffer;
+}
+/**
+ * 页面结构
+ * 表示 .light 文件中的一个数据页
+ */
+export interface Page {
+    /** 页面ID */
+    pageId: number;
+    /** 页面中的记录列表 */
+    records: Record[];
+    /** 页面校验和 */
+    checksum: number;
+}
+/**
+ * WAL 记录结构
+ * 表示预写日志中的一条记录
+ */
+export interface WalRecord {
+    /** 日志序列号，单调递增 */
+    lsn: bigint;
+    /** 事务ID */
+    transactionId: bigint;
+    /** 操作类型 */
+    operationType: OperationType;
+    /** 操作的键 */
+    key: string;
+    /** 操作的值（可选，删除操作无值） */
+    value: Buffer | null;
+    /** 记录校验和 */
+    checksum: number;
+}
+/**
+ * SHM 文件头部结构
+ * 存储 WAL 索引的元信息
+ */
+export interface ShmHeader {
+    /** 当前 WAL 文件大小 */
+    walFileSize: bigint;
+    /** 最后一个完整页的 LSN */
+    lastCompleteLsn: bigint;
+    /** 哈希表中记录数量 */
+    recordCount: number;
+    /** 头部校验和 */
+    checksum: number;
+}
+/**
+ * SHM 哈希表条目
+ * 用于快速定位 WAL 中每个页面的最新记录
+ */
+export interface ShmEntry {
+    /** 页面ID */
+    pageId: number;
+    /** 该页面最新记录的 LSN */
+    lsn: bigint;
+    /** 该记录在 WAL 文件中的偏移量 */
+    walOffset: bigint;
+}
+/**
+ * 存储引擎配置选项
+ */
+export interface StorageEngineOptions {
+    /** 页面大小（字节），默认 4KB */
+    pageSize?: number;
+    /** WAL 文件大小阈值，超过此值自动触发检查点，默认 16MB */
+    walThreshold?: number;
+    /** 是否启用自动检查点，默认 true */
+    autoCheckpoint?: boolean;
+    /** fsync 策略：每次写入、每N条、或每N毫秒 */
+    fsyncStrategy?: FsyncStrategy;
+}
+/**
+ * fsync 策略配置
+ */
+export interface FsyncStrategy {
+    /** 策略类型 */
+    type: "always" | "batch" | "interval";
+    /** 批量模式下，每N条记录 fsync 一次 */
+    batchSize?: number;
+    /** 间隔模式下，每N毫秒 fsync 一次 */
+    intervalMs?: number;
+}
+/**
+ * 检查点结果
+ */
+export interface CheckpointResult {
+    /** 检查点完成时间 */
+    timestamp: number;
+    /** 检查点时的 LSN */
+    lsn: bigint;
+    /** 写入的页面数量 */
+    pagesWritten: number;
+    /** 写入的总字节数 */
+    bytesWritten: number;
+}
+/**
+ * 恢复结果
+ */
+export interface RecoveryResult {
+    /** 恢复是否成功 */
+    success: boolean;
+    /** 回放的 WAL 记录数量 */
+    recordsReplayed: number;
+    /** 加载的页面数量 */
+    pagesLoaded: number;
+    /** 恢复耗时（毫秒） */
+    durationMs: number;
+    /** 错误信息（如果恢复失败） */
+    error?: string;
+}
+/**
+ * 存储引擎统计信息
+ */
+export interface StorageStats {
+    /** 当前 LSN */
+    currentLsn: bigint;
+    /** 当前事务ID */
+    currentTransactionId: bigint;
+    /** WAL 文件大小 */
+    walFileSize: number;
+    /** .light 文件大小 */
+    lightFileSize: number;
+    /** 页面数量 */
+    pageCount: number;
+    /** 记录数量 */
+    recordCount: number;
+    /** 上次检查点时间 */
+    lastCheckpointTime: number | null;
+}
+/**
+ * 写操作结果
+ */
+export interface WriteResult {
+    /** 操作是否成功 */
+    success: boolean;
+    /** 分配的 LSN */
+    lsn: bigint;
+    /** 写入的字节数 */
+    bytesWritten: number;
+}
+/**
+ * 批量写操作结果
+ */
+export interface BatchWriteResult {
+    /** 操作是否成功 */
+    success: boolean;
+    /** 起始 LSN */
+    startLsn: bigint;
+    /** 结束 LSN */
+    endLsn: bigint;
+    /** 总写入字节数 */
+    totalBytesWritten: number;
+    /** 成功的记录数量 */
+    recordsWritten: number;
+}
+/**
+ * 哈希表迭代器结果
+ */
+export interface HashIteratorResult {
+    /** 条目数据 */
+    entry: ShmEntry;
+    /** 是否还有更多条目 */
+    done: boolean;
+}
+/**
+ * 文件句柄包装接口
+ * 提供统一的文件操作抽象
+ */
+export interface FileHandle {
+    /** 读取文件内容 */
+    read(buffer: Buffer, offset: number, length: number, position: number): Promise<number>;
+    /** 写入文件内容 */
+    write(buffer: Buffer, offset: number, length: number, position: number): Promise<number>;
+    /** 同步文件到磁盘 */
+    sync(): Promise<void>;
+    /** 关闭文件句柄 */
+    close(): Promise<void>;
+    /** 获取文件大小 */
+    size(): Promise<number>;
+}
+/**
+ * 内存中的数据页映射
+ */
+export type PageMap = Map<number, Page>;
+/**
+ * 内存中的记录映射
+ */
+export type RecordMap = Map<string, Buffer>;
+/**
+ * WAL 记录迭代器
+ */
+export type WalRecordIterator = AsyncGenerator<WalRecord, void, unknown>;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/types/index.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * LightDB 存储引擎类型定义
+ * 包含所有公共接口、类型和结构体定义
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/utils/binary.d.ts

@@ -0,0 +1,271 @@
+/**
+ * 二进制序列化工具类
+ * 提供 Buffer 读写、校验和计算等核心功能
+ */
+/**
+ * 二进制工具类
+ * 提供静态方法用于 Buffer 操作和校验和计算
+ */
+export declare class BinaryUtils {
+    /**
+     * 计算 Buffer 的 CRC32 校验和
+     * @param data 要计算校验和的数据
+     * @param offset 起始偏移量，默认 0
+     * @param length 数据长度，默认到末尾
+     * @returns CRC32 校验和（无符号 32 位整数）
+     */
+    static calculateChecksum(data: Buffer, offset?: number, length?: number): number;
+    /**
+     * 验证校验和
+     * @param data 数据内容
+     * @param expectedChecksum 期望的校验和
+     * @param offset 数据起始偏移量
+     * @param length 数据长度
+     * @throws ChecksumError 如果校验和不匹配
+     */
+    static verifyChecksum(data: Buffer, expectedChecksum: number, offset?: number, length?: number): void;
+    /**
+     * 读取无符号 8 位整数
+     * @param buffer 数据缓冲区
+     * @param offset 偏移量
+     */
+    static readUInt8(buffer: Buffer, offset: number): number;
+    /**
+     * 写入无符号 8 位整数
+     * @param buffer 数据缓冲区
+     * @param value 值
+     * @param offset 偏移量
+     */
+    static writeUInt8(buffer: Buffer, value: number, offset: number): void;
+    /**
+     * 读取无符号 16 位整数（Little-Endian）
+     * @param buffer 数据缓冲区
+     * @param offset 偏移量
+     */
+    static readUInt16LE(buffer: Buffer, offset: number): number;
+    /**
+     * 写入无符号 16 位整数（Little-Endian）
+     * @param buffer 数据缓冲区
+     * @param value 值
+     * @param offset 偏移量
+     */
+    static writeUInt16LE(buffer: Buffer, value: number, offset: number): void;
+    /**
+     * 读取无符号 32 位整数（Little-Endian）
+     * @param buffer 数据缓冲区
+     * @param offset 偏移量
+     */
+    static readUInt32LE(buffer: Buffer, offset: number): number;
+    /**
+     * 写入无符号 32 位整数（Little-Endian）
+     * @param buffer 数据缓冲区
+     * @param value 值
+     * @param offset 偏移量
+     */
+    static writeUInt32LE(buffer: Buffer, value: number, offset: number): void;
+    /**
+     * 读取有符号 32 位整数（Little-Endian）
+     * @param buffer 数据缓冲区
+     * @param offset 偏移量
+     */
+    static readInt32LE(buffer: Buffer, offset: number): number;
+    /**
+     * 写入有符号 32 位整数（Little-Endian）
+     * @param buffer 数据缓冲区
+     * @param value 值
+     * @param offset 偏移量
+     */
+    static writeInt32LE(buffer: Buffer, value: number, offset: number): void;
+    /**
+     * 读取无符号 64 位整数（Little-Endian）
+     * 返回 BigInt 类型
+     * @param buffer 数据缓冲区
+     * @param offset 偏移量
+     */
+    static readBigUInt64LE(buffer: Buffer, offset: number): bigint;
+    /**
+     * 写入无符号 64 位整数（Little-Endian）
+     * @param buffer 数据缓冲区
+     * @param value 值
+     * @param offset 偏移量
+     */
+    static writeBigUInt64LE(buffer: Buffer, value: bigint, offset: number): void;
+    /**
+     * 读取字符串（UTF-8 编码）
+     * @param buffer 数据缓冲区
+     * @param offset 起始偏移量
+     * @param length 字符串字节长度
+     */
+    static readString(buffer: Buffer, offset: number, length: number): string;
+    /**
+     * 写入字符串（UTF-8 编码）
+     * @param buffer 数据缓冲区
+     * @param value 字符串值
+     * @param offset 起始偏移量
+     * @returns 实际写入的字节数
+     */
+    static writeString(buffer: Buffer, value: string, offset: number): number;
+    /**
+     * 计算字符串的字节长度（UTF-8 编码）
+     * @param value 字符串值
+     */
+    static stringByteLength(value: string): number;
+    /**
+     * 分配指定大小的 Buffer（未初始化）
+     * 比 Buffer.alloc 更快，但内容未定义
+     * @param size Buffer 大小
+     */
+    static allocUnsafe(size: number): Buffer;
+    /**
+     * 分配指定大小的 Buffer（初始化为零）
+     * @param size Buffer 大小
+     */
+    static alloc(size: number): Buffer;
+    /**
+     * 连接多个 Buffer
+     * @param buffers Buffer 数组
+     */
+    static concat(buffers: Buffer[]): Buffer;
+    /**
+     * 复制 Buffer 的一部分
+     * @param source 源 Buffer
+     * @param start 起始位置
+     * @param end 结束位置
+     */
+    static slice(source: Buffer, start: number, end?: number): Buffer;
+    /**
+     * 比较两个 Buffer 是否相等
+     * @param a 第一个 Buffer
+     * @param b 第二个 Buffer
+     */
+    static equals(a: Buffer, b: Buffer): boolean;
+}
+/**
+ * Buffer 写入器
+ * 提供便捷的顺序写入功能
+ */
+export declare class BufferWriter {
+    private buffer;
+    private offset;
+    /**
+     * 创建 Buffer 写入器
+     * @param size 初始 Buffer 大小
+     */
+    constructor(size: number);
+    /**
+     * 获取当前写入位置
+     */
+    get position(): number;
+    /**
+     * 获取已写入的数据
+     */
+    get data(): Buffer;
+    /**
+     * 确保有足够的空间
+     * @param additional 需要的额外空间
+     */
+    private ensureCapacity;
+    /**
+     * 写入无符号 8 位整数
+     */
+    writeUInt8(value: number): this;
+    /**
+     * 写入无符号 16 位整数（Little-Endian）
+     */
+    writeUInt16LE(value: number): this;
+    /**
+     * 写入无符号 32 位整数（Little-Endian）
+     */
+    writeUInt32LE(value: number): this;
+    /**
+     * 写入无符号 64 位整数（Little-Endian）
+     */
+    writeBigUInt64LE(value: bigint): this;
+    /**
+     * 写入字符串（带长度前缀）
+     */
+    writeString(value: string): this;
+    /**
+     * 写入字符串（不带长度前缀）
+     */
+    writeStringRaw(value: string): this;
+    /**
+     * 写入 Buffer
+     */
+    writeBuffer(value: Buffer): this;
+    /**
+     * 写入带长度前缀的 Buffer
+     */
+    writeBufferWithLength(value: Buffer): this;
+    /**
+     * 写入校验和（计算从起始位置到当前位置的数据）
+     */
+    writeChecksum(startOffset?: number): this;
+}
+/**
+ * Buffer 读取器
+ * 提供便捷的顺序读取功能
+ */
+export declare class BufferReader {
+    private buffer;
+    private offset;
+    /**
+     * 创建 Buffer 读取器
+     * @param buffer 要读取的 Buffer
+     * @param startOffset 起始偏移量，默认 0
+     */
+    constructor(buffer: Buffer, startOffset?: number);
+    /**
+     * 获取当前读取位置
+     */
+    get position(): number;
+    /**
+     * 设置读取位置
+     */
+    set position(value: number);
+    /**
+     * 获取剩余可读字节数
+     */
+    get remaining(): number;
+    /**
+     * 检查是否有足够的可读数据
+     */
+    hasRemaining(required: number): boolean;
+    /**
+     * 读取无符号 8 位整数
+     */
+    readUInt8(): number;
+    /**
+     * 读取无符号 16 位整数（Little-Endian）
+     */
+    readUInt16LE(): number;
+    /**
+     * 读取无符号 32 位整数（Little-Endian）
+     */
+    readUInt32LE(): number;
+    /**
+     * 读取无符号 64 位整数（Little-Endian）
+     */
+    readBigUInt64LE(): bigint;
+    /**
+     * 读取字符串（带长度前缀）
+     */
+    readString(): string;
+    /**
+     * 读取指定长度的 Buffer
+     */
+    readBuffer(length: number): Buffer;
+    /**
+     * 读取带长度前缀的 Buffer
+     */
+    readBufferWithLength(): Buffer;
+    /**
+     * 读取并验证校验和
+     */
+    readAndVerifyChecksum(startOffset: number): number;
+    /**
+     * 跳过指定字节数
+     */
+    skip(bytes: number): this;
+}
+//# sourceMappingURL=binary.d.ts.map

package/dist/utils/binary.d.ts.map

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