@yydb/light-db 0.0.0 → 0.0.11

package/dist/core/records.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 记录存储
+ *
+ * 数据库在内存中的键值视图。值在写入与读取时都做一次复制，
+ * 避免调用方持有内部字节数组造成校验和与快照不一致。
+ */
+/**
+ * 内存记录存储
+ */
+export declare class RecordStore {
+    private records;
+    /**
+     * 读取值
+     * @param key 键
+     */
+    get(key: string): Uint8Array | null;
+    /**
+     * 是否存在键
+     * @param key 键
+     */
+    has(key: string): boolean;
+    /**
+     * 写入值
+     * @param key 键
+     * @param value 值
+     */
+    put(key: string, value: Uint8Array): void;
+    /**
+     * 删除键
+     * @param key 键
+     */
+    delete(key: string): boolean;
+    /** 记录数量 */
+    get size(): number;
+    /**
+     * 快照当前记录
+     *
+     * 返回只读视图，供检查点打包使用。
+     */
+    snapshot(): ReadonlyMap<string, Uint8Array>;
+    /**
+     * 用恢复结果替换全部记录
+     * @param records 记录映射
+     */
+    restore(records: ReadonlyMap<string, Uint8Array>): void;
+    /** 清空所有记录 */
+    clear(): void;
+}
+//# sourceMappingURL=records.d.ts.map

package/dist/core/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/core/records.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,OAAO,CAAsC;IAErD;;;OAGG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAK1C;;;OAGG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAIhD;;;OAGG;IACI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW;IACX,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACI,QAAQ,IAAI,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC;IAIlD;;;OAGG;IACI,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,IAAI;IAO9D,aAAa;IACN,KAAK,IAAI,IAAI;CAGvB"}

package/dist/core/records.js

@@ -0,0 +1,70 @@
+/**
+ * 记录存储
+ *
+ * 数据库在内存中的键值视图。值在写入与读取时都做一次复制，
+ * 避免调用方持有内部字节数组造成校验和与快照不一致。
+ */
+import { BinaryUtils } from '../codec';
+/**
+ * 内存记录存储
+ */
+export class RecordStore {
+    records = new Map();
+    /**
+     * 读取值
+     * @param key 键
+     */
+    get(key) {
+        const value = this.records.get(key);
+        return value ? BinaryUtils.copy(value) : null;
+    }
+    /**
+     * 是否存在键
+     * @param key 键
+     */
+    has(key) {
+        return this.records.has(key);
+    }
+    /**
+     * 写入值
+     * @param key 键
+     * @param value 值
+     */
+    put(key, value) {
+        this.records.set(key, BinaryUtils.copy(value));
+    }
+    /**
+     * 删除键
+     * @param key 键
+     */
+    delete(key) {
+        return this.records.delete(key);
+    }
+    /** 记录数量 */
+    get size() {
+        return this.records.size;
+    }
+    /**
+     * 快照当前记录
+     *
+     * 返回只读视图，供检查点打包使用。
+     */
+    snapshot() {
+        return this.records;
+    }
+    /**
+     * 用恢复结果替换全部记录
+     * @param records 记录映射
+     */
+    restore(records) {
+        this.records = new Map();
+        for (const [key, value] of records) {
+            this.records.set(key, BinaryUtils.copy(value));
+        }
+    }
+    /** 清空所有记录 */
+    clear() {
+        this.records.clear();
+    }
+}
+//# sourceMappingURL=records.js.map

package/dist/core/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../src/core/records.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC;;GAEG;AACH,MAAM,OAAO,WAAW;IACZ,OAAO,GAA4B,IAAI,GAAG,EAAE,CAAC;IAErD;;;OAGG;IACI,GAAG,CAAC,GAAW;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,CAAC;IAED;;;OAGG;IACI,GAAG,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,GAAG,CAAC,GAAW,EAAE,KAAiB;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,GAAW;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,WAAW;IACX,IAAW,IAAI;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACI,QAAQ;QACX,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;;OAGG;IACI,OAAO,CAAC,OAAwC;QACnD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACnD,CAAC;IACL,CAAC;IAED,aAAa;IACN,KAAK;QACR,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACJ"}

package/dist/core/recovery.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 崩溃恢复
+ *
+ * 读取最近一次快照，再按 WAL 顺序重放快照之后的记录。
+ */
+import type { StorageAdapter } from '../storage/StorageAdapter';
+import type { WalLog } from './wal';
+/** 恢复结果 */
+export interface RecoveryOutcome {
+    /** 恢复后的记录 */
+    records: Map<string, Uint8Array>;
+    /** 已覆盖到的最大 LSN */
+    lastLsn: bigint;
+    /** 载入的页数量 */
+    pagesLoaded: number;
+    /** 重放的 WAL 记录数量 */
+    recordsReplayed: number;
+    /** 丢弃的不完整 WAL 尾字节数 */
+    discardedTailBytes: number;
+}
+/**
+ * 恢复管理器
+ */
+export declare class RecoveryManager {
+    private readonly adapter;
+    constructor(adapter: StorageAdapter);
+    /**
+     * 执行恢复
+     * @param wal 已打开的 WAL
+     */
+    recover(wal: WalLog): Promise<RecoveryOutcome>;
+    /**
+     * 读取快照，不存在时返回空记录
+     */
+    private loadSnapshot;
+    /**
+     * 应用一条 WAL 记录
+     * @param records 记录映射
+     * @param record WAL 记录
+     */
+    private apply;
+}
+//# sourceMappingURL=recovery.d.ts.map

package/dist/core/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/core/recovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEpC,WAAW;AACX,MAAM,WAAW,eAAe;IAC5B,aAAa;IACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACjC,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;gBAE7B,OAAO,EAAE,cAAc;IAInC;;;OAGG;IACU,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B3D;;OAEG;YACW,YAAY;IAoC1B;;;;OAIG;IACH,OAAO,CAAC,KAAK;CAchB"}

package/dist/core/recovery.js

@@ -0,0 +1,99 @@
+/**
+ * 崩溃恢复
+ *
+ * 读取最近一次快照，再按 WAL 顺序重放快照之后的记录。
+ */
+import { ChecksumMismatchError, decodeSnapshot, SnapshotFormatError } from '../codec';
+import { WalOperation } from '../codec';
+import { LightDbError, LightDbErrorCodes } from '../errors';
+/**
+ * 恢复管理器
+ */
+export class RecoveryManager {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * 执行恢复
+     * @param wal 已打开的 WAL
+     */
+    async recover(wal) {
+        const snapshot = await this.loadSnapshot();
+        const { records: walRecords, validBytes, fileSize } = await wal.readAll();
+        if (validBytes < fileSize) {
+            await wal.truncate(validBytes);
+        }
+        let recordsReplayed = 0;
+        let lastLsn = snapshot.lastSnapshotLsn;
+        for (const record of walRecords) {
+            if (record.lsn <= snapshot.lastSnapshotLsn) {
+                continue;
+            }
+            this.apply(snapshot.records, record);
+            lastLsn = record.lsn > lastLsn ? record.lsn : lastLsn;
+            recordsReplayed++;
+        }
+        return {
+            records: snapshot.records,
+            lastLsn,
+            pagesLoaded: snapshot.pagesLoaded,
+            recordsReplayed,
+            discardedTailBytes: fileSize - validBytes,
+        };
+    }
+    /**
+     * 读取快照，不存在时返回空记录
+     */
+    async loadSnapshot() {
+        if (!(await this.adapter.exists('main'))) {
+            return { records: new Map(), lastSnapshotLsn: 0n, pagesLoaded: 0 };
+        }
+        const handle = await this.adapter.open('main', 'read');
+        let data;
+        try {
+            const size = await handle.size();
+            data = await handle.read(0, size);
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            const snapshot = decodeSnapshot(data);
+            return {
+                records: snapshot.records,
+                lastSnapshotLsn: snapshot.header.lastSnapshotLsn,
+                pagesLoaded: snapshot.pageCount,
+            };
+        }
+        catch (error) {
+            if (error instanceof SnapshotFormatError || error instanceof ChecksumMismatchError) {
+                throw new LightDbError(LightDbErrorCodes.corrupt, 'database snapshot is corrupt', {
+                    operation: 'recover',
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * 应用一条 WAL 记录
+     * @param records 记录映射
+     * @param record WAL 记录
+     */
+    apply(records, record) {
+        switch (record.operation) {
+            case WalOperation.Put:
+                if (record.value) {
+                    records.set(record.key, record.value);
+                }
+                break;
+            case WalOperation.Delete:
+                records.delete(record.key);
+                break;
+            case WalOperation.Checkpoint:
+                break;
+        }
+    }
+}
+//# sourceMappingURL=recovery.js.map

package/dist/core/recovery.js.map

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

package/dist/core/wal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * WAL 日志
+ *
+ * 只通过 `StorageAdapter` 访问平台，记录格式由 `codec/record` 决定。
+ */
+import type { WalRecord } from '../codec';
+import type { StorageAdapter } from '../storage/StorageAdapter';
+/**
+ * 预写日志
+ */
+export declare class WalLog {
+    private readonly adapter;
+    private handle;
+    private offset;
+    constructor(adapter: StorageAdapter);
+    /** 当前日志字节数 */
+    get byteSize(): number;
+    /**
+     * 打开日志，定位到末尾
+     */
+    open(): Promise<void>;
+    /**
+     * 追加记录并等待落盘
+     * @param records 记录
+     */
+    append(records: readonly WalRecord[]): Promise<number>;
+    /**
+     * 读取全部完整记录
+     *
+     * 末尾不完整的记录（写入过程中断）会被丢弃，`validBytes` 指向最后一个完整记录之后。
+     */
+    readAll(): Promise<{
+        records: WalRecord[];
+        validBytes: number;
+        fileSize: number;
+    }>;
+    /**
+     * 截断日志
+     * @param size 目标字节数，默认 0
+     */
+    truncate(size?: number): Promise<void>;
+    /** 关闭日志 */
+    close(): Promise<void>;
+    /**
+     * 获取已打开的句柄
+     * @param operation 操作名
+     */
+    private requireHandle;
+}
+//# sourceMappingURL=wal.d.ts.map

package/dist/core/wal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wal.d.ts","sourceRoot":"","sources":["../../src/core/wal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,2BAA2B,CAAC;AAE/E;;GAEG;AACH,qBAAa,MAAM;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,MAAM,CAAa;gBAEf,OAAO,EAAE,cAAc;IAInC,cAAc;IACd,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC;;;OAGG;IACU,MAAM,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBnE;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAiC/F;;;OAGG;IACU,QAAQ,CAAC,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD,WAAW;IACE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnC;;;OAGG;IACH,OAAO,CAAC,aAAa;CAMxB"}

package/dist/core/wal.js

@@ -0,0 +1,114 @@
+/**
+ * WAL 日志
+ *
+ * 只通过 `StorageAdapter` 访问平台，记录格式由 `codec/record` 决定。
+ */
+import { ChecksumMismatchError, decodeWalRecord, encodeWalRecord } from '../codec';
+import { LightDbError, LightDbErrorCodes } from '../errors';
+/**
+ * 预写日志
+ */
+export class WalLog {
+    adapter;
+    handle = null;
+    offset = 0;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /** 当前日志字节数 */
+    get byteSize() {
+        return this.offset;
+    }
+    /**
+     * 打开日志，定位到末尾
+     */
+    async open() {
+        this.handle = await this.adapter.open('wal', 'readwrite');
+        this.offset = await this.handle.size();
+    }
+    /**
+     * 追加记录并等待落盘
+     * @param records 记录
+     */
+    async append(records) {
+        if (records.length === 0) {
+            return 0;
+        }
+        const handle = this.requireHandle('walAppend');
+        const encoded = records.map((record) => encodeWalRecord(record));
+        const total = encoded.reduce((sum, part) => sum + part.length, 0);
+        const buffer = new Uint8Array(total);
+        let position = 0;
+        for (const part of encoded) {
+            buffer.set(part, position);
+            position += part.length;
+        }
+        await handle.write(this.offset, buffer);
+        await handle.sync();
+        this.offset += total;
+        return total;
+    }
+    /**
+     * 读取全部完整记录
+     *
+     * 末尾不完整的记录（写入过程中断）会被丢弃，`validBytes` 指向最后一个完整记录之后。
+     */
+    async readAll() {
+        const handle = this.requireHandle('walRead');
+        const size = await handle.size();
+        if (size === 0) {
+            return { records: [], validBytes: 0, fileSize: 0 };
+        }
+        const data = await handle.read(0, size);
+        const records = [];
+        let offset = 0;
+        while (offset < data.length) {
+            try {
+                const decoded = decodeWalRecord(data, offset);
+                if (decoded.status === 'incomplete') {
+                    break;
+                }
+                records.push(decoded.record);
+                offset += decoded.bytesRead;
+            }
+            catch (error) {
+                if (error instanceof ChecksumMismatchError) {
+                    throw new LightDbError(LightDbErrorCodes.corrupt, `WAL record is corrupt at offset ${offset}`, {
+                        operation: 'walRead',
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+        }
+        return { records, validBytes: offset, fileSize: size };
+    }
+    /**
+     * 截断日志
+     * @param size 目标字节数，默认 0
+     */
+    async truncate(size = 0) {
+        const handle = this.requireHandle('walTruncate');
+        await handle.truncate(size);
+        await handle.sync();
+        this.offset = size;
+    }
+    /** 关闭日志 */
+    async close() {
+        if (this.handle) {
+            await this.handle.close();
+            this.handle = null;
+        }
+    }
+    /**
+     * 获取已打开的句柄
+     * @param operation 操作名
+     */
+    requireHandle(operation) {
+        if (!this.handle) {
+            throw new LightDbError(LightDbErrorCodes.sessionClosed, 'WAL is not open', { operation });
+        }
+        return this.handle;
+    }
+}
+//# sourceMappingURL=wal.js.map

package/dist/core/wal.js.map

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

package/dist/errors/index.d.ts

@@ -1,69 +1,47 @@
 /**
- * LightDB 存储引擎错误定义
- * 提供详细的错误类型和错误消息
- */
-/**
- * 存储引擎错误基类
- */
-export declare class StorageError extends Error {
-    /** 错误代码 */
+ * 稳定错误模型
+ *
+ * 与 `@yydb/yydb` / `@yydb/yydb-client` 共用同一组错误码：宿主只按 `code` 分支，
+ * `message` 只用于显示。
+ */
+/** 浏览器产品对外的稳定错误码 */
+export declare const LightDbErrorCodes: {
+    /** I/O 失败 */
+    readonly io: "yydb.io";
+    /** 持久化数据损坏 */
+    readonly corrupt: "yydb.corrupt";
+    /** Schema 文档与已持久化内容冲突 */
+    readonly schemaConflict: "yydb.schema.conflict";
+    /** Schema 文档不合法 */
+    readonly schemaInvalid: "yydb.schema.invalid";
+    /** 宿主不支持该能力 */
+    readonly unsupported: "yydb.unsupported";
+    /** 会话或数据库已关闭 */
+    readonly sessionClosed: "yydb.session.closed";
+    /** 单写者租约不可用（例如缺少 Web Locks） */
+    readonly leaseUnavailable: "yydb.lease.unavailable";
+    /** 存储配额不足 */
+    readonly quotaExceeded: "yydb.quota.exceeded";
+};
+/**
+ * 数据库错误选项
+ */
+export interface LightDbErrorOptions {
+    /** 失败的操作（`schemaGet`、`kvPut` 等） */
+    operation?: string;
+    /** 底层失败 */
+    cause?: unknown;
+}
+/**
+ * 携带稳定错误码的数据库错误
+ */
+export declare class LightDbError extends Error {
+    /** 稳定错误码 */
     readonly code: string;
-    /** 错误上下文信息 */
-    readonly context?: Record<string, unknown>;
-    constructor(message: string, code: string, context?: Record<string, unknown>);
-}
-/**
- * 文件操作错误
- */
-export declare class FileOperationError extends StorageError {
-    constructor(message: string, filePath: string, operation: string);
-}
-/**
- * 文件格式错误
- */
-export declare class FileFormatError extends StorageError {
-    constructor(message: string, filePath: string, expected?: string, actual?: unknown);
-}
-/**
- * 校验和错误
- */
-export declare class ChecksumError extends StorageError {
-    constructor(message: string, expected: number, actual: number, position?: number);
-}
-/**
- * WAL 错误
- */
-export declare class WalError extends StorageError {
-    constructor(message: string, lsn?: bigint, offset?: number);
-}
-/**
- * 恢复错误
- */
-export declare class RecoveryError extends StorageError {
-    constructor(message: string, phase: string, details?: unknown);
-}
-/**
- * 检查点错误
- */
-export declare class CheckpointError extends StorageError {
-    constructor(message: string, lsn?: bigint);
-}
-/**
- * 页面错误
- */
-export declare class PageError extends StorageError {
-    constructor(message: string, pageId: number, details?: unknown);
-}
-/**
- * 序列化错误
- */
-export declare class SerializationError extends StorageError {
-    constructor(message: string, data?: unknown);
-}
-/**
- * 配置错误
- */
-export declare class ConfigurationError extends StorageError {
-    constructor(message: string, option?: string, value?: unknown);
+    /** 失败的操作 */
+    readonly operation: string;
+    /** 是否可以用相同参数重试 */
+    readonly retryable: boolean;
+    constructor(code: string, message: string, options?: LightDbErrorOptions);
 }
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACnC,WAAW;IACX,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,cAAc;IACd,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAS/E;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACpC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAKnE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACjC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;CAKrF;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;gBAC/B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CAKnF;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,YAAY;gBAC1B,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK7D;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;gBAC/B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAKhE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACjC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAK5C;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,YAAY;gBAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAKjE;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACpC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAK9C;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACpC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAKhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oBAAoB;AACpB,eAAO,MAAM,iBAAiB;IAC1B,aAAa;;IAEb,cAAc;;IAEd,yBAAyB;;IAEzB,mBAAmB;;IAEnB,eAAe;;IAEf,gBAAgB;;IAEhB,+BAA+B;;IAE/B,aAAa;;CAEP,CAAC;AAKX;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW;IACX,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACnC,YAAY;IACZ,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,YAAY;IACZ,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC,kBAAkB;IAClB,SAAgB,SAAS,EAAE,OAAO,CAAC;gBAEvB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;CAQ/E"}