@andrew_l/binlog 0.2.14

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Andrew L. <andrew.io.dev@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# Binlog
+
+![license](https://img.shields.io/npm/l/%40andrew_l%2Fbinlog) <!-- omit in toc -->
+![npm version](https://img.shields.io/npm/v/%40andrew_l%2Fbinlog) <!-- omit in toc -->
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40andrew_l%2Fbinlog) <!-- omit in toc -->
+
+A high-performance binary logging system for Node.js applications, inspired by VK's KPHP KDB binlog implementation. This library provides a robust, efficient way to record and replay binary log entries with integrity checking and rotation support.
+
+## 📋 Features
+
+- **Automatic log rotation** based on file size
+- **TL serialization** integration for complex data types
+- **Data integrity** verification via CRC32 checksums
+- **File system sync control** for durability vs performance tradeoffs
+
+<!-- install placeholder -->
+
+## 🔧 Usage
+
+### Basic Example
+
+```typescript
+import { createBinlog } from '@andrew_l/binlog';
+
+async function main() {
+  // Create a binlog with default options
+  const binlog = createBinlog({
+    path: './logs/app-{index}.bin',
+  });
+
+  // Initialize binlog system
+  await binlog.init();
+
+  // Open the binlog for writing
+  await binlog.open();
+
+  // Write entries with various opcodes and data
+  await binlog.write(1, { message: 'Application started' });
+  await binlog.write(2, { user: 'john', action: 'login' });
+
+  // Close the binlog when done
+  await binlog.close();
+}
+
+main().catch(console.error);
+```
+
+### Reading Binlog Entries
+
+```typescript
+import { createBinlog } from '@andrew_l/binlog';
+
+async function readLogs() {
+  const binlog = createBinlog({
+    path: './logs/app-{index}.bin',
+  });
+
+  await binlog.init();
+
+  // Read entries from a specific binlog file
+  const entries = await binlog.readEntries<{
+    message?: string;
+    user?: string;
+    action?: string;
+  }>('app-0.bin');
+
+  // Process entries
+  for (const entry of entries) {
+    console.log(
+      `[${new Date(entry.timestamp * 1000).toISOString()}] Op: ${entry.opcode}`,
+    );
+    console.log(entry.data);
+  }
+}
+
+readLogs().catch(console.error);
+```
+
+### Configuration Options
+
+```typescript
+import { createBinlog } from '@andrew_l/binlog';
+
+const binlog = createBinlog({
+  // File path pattern with {index} placeholder for rotation
+  path: './logs/application-{index}.bin',
+
+  // Maximum file size before rotation (100MB)
+  maxFileSize: 104857600,
+
+  // Enable/disable log rotation
+  rotation: true,
+
+  // Control synchronous writes for durability
+  syncWrites: true,
+});
+```
+
+## ⚙️ API Reference
+
+#### Methods
+
+- **`async init(): Promise<void>`**  
+  Initialize the binlog system, ensuring directory exists and pick most recent binlog file.
+
+- **`async open(): Promise<void>`**  
+  Open the binlog for writing.
+
+- **`async close(): Promise<void>`**  
+  Close the current binlog file.
+
+- **`async write(opcode: number, data: unknown): Promise<void>`**  
+  Write a binlog entry with the specified opcode and data.
+
+- **`async rotate(): Promise<void>`**  
+  Rotate the binlog file to a new one.
+
+- **`async readEntries<TData = Buffer>(filename: string, unsafe?: boolean): Promise<BinlogEntry<TData>[]>`**  
+  Read and parse all entries from a binlog file.
+
+#### Properties
+
+- **`currentFileIndex: number`**  
+  Get the current binlog file index.
+
+- **`currentFileName: string`**  
+  Get current binlog file name.
+
+- **`directory: string`**  
+  Get current binlog directory.
+
+## 🛡️ Binlog File Format
+
+Each binlog file has:
+
+- **File Header** (16 bytes)
+
+  - Magic number (4 bytes): 0x4442544B
+  - Version (4 bytes): Currently 1
+  - Timestamp (4 bytes)
+  - Reserved (4 bytes)
+
+- **Entry Headers** (20 bytes each)
+
+  - Operation code (4 bytes)
+  - Flags (4 bytes)
+  - Timestamp (4 bytes)
+  - Data length (4 bytes)
+  - CRC32 checksum (4 bytes)
+
+- **Entry Data** (variable length)
+  - Raw binary data or TL-encoded data
+
+## 🔄 Integration with TL-Pack
+
+Binlog automatically uses TL serialization for non-Buffer data types using the `@andrew_l/tl-pack` library. This allows for efficient serialization of complex JavaScript objects.
+
+```typescript
+// Data will be automatically TL-encoded
+await binlog.write(1, {
+  user: 'alice',
+  permissions: ['read', 'write'],
+  metadata: {
+    lastLogin: new Date(),
+    requestCount: 42,
+  },
+});
+```
+
+## 📝 License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,260 @@
+'use strict';
+
+const toolkit = require('@andrew_l/toolkit');
+const tlPack = require('@andrew_l/tl-pack');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+const path__default = /*#__PURE__*/_interopDefaultCompat(path);
+
+class Binlog {
+  _options;
+  _filePattern;
+  _directory;
+  _currentFile;
+  _currentFileDescriptor;
+  _currentFileSize;
+  _currentFileIndex;
+  _isOpen;
+  _log;
+  BINLOG_MAGIC = 1145197643;
+  BINLOG_VERSION = 1;
+  BINLOG_HEADER_SIZE = 16;
+  BINLOG_ENTRY_HEADER_SIZE = 20;
+  BINLOG_FLAG = Object.freeze({
+    NONE: 0,
+    TL: 1 << 0
+  });
+  constructor(options) {
+    this._log = toolkit.logger("Binlog");
+    this._options = toolkit.deepClone(options);
+    this._filePattern = path__default.basename(options.path);
+    this._directory = path__default.dirname(options.path);
+    this._currentFile = null;
+    this._currentFileDescriptor = null;
+    this._currentFileSize = 0;
+    this._currentFileIndex = 0;
+    this._isOpen = false;
+  }
+  /**
+   * Initialize the binlog system, ensuring directory exists and pick most recent binlog file
+   * @returns Promise resolving to true if successful, false otherwise
+   */
+  async init() {
+    await fs__default.promises.mkdir(this._directory, { recursive: true });
+    await this.#findLatestBinlogFile();
+  }
+  /**
+   * Find the latest binlog file to continue writing
+   */
+  async #findLatestBinlogFile() {
+    const files = await fs__default.promises.readdir(this._directory);
+    const fileRegEx = filePatternToRegex(this._filePattern);
+    this._currentFileIndex = 0;
+    for (const fileName of files) {
+      const match = fileName.match(fileRegEx);
+      if (match) {
+        this._currentFileIndex = Math.max(
+          this._currentFileIndex,
+          parseInt(match[1], 10)
+        );
+      }
+    }
+  }
+  /**
+   * Open the binlog for writing
+   */
+  async open() {
+    const filePath = path__default.join(this._directory, this.currentFileName);
+    this._currentFileDescriptor = await fs__default.promises.open(filePath, "a+");
+    this._currentFile = filePath;
+    this._currentFileSize = (await this._currentFileDescriptor.stat()).size;
+    this._isOpen = true;
+    if (this._currentFileSize === 0) {
+      await this.#writeBinlogHeader();
+    } else {
+      await this.#checkBinlogHeaders(this._currentFileDescriptor);
+    }
+  }
+  /**
+   * Close the current binlog file
+   */
+  async close() {
+    if (!this._isOpen || !this._currentFileDescriptor) return;
+    await this._currentFileDescriptor.close();
+    this._currentFileDescriptor = null;
+    this._currentFile = null;
+    this._isOpen = false;
+  }
+  /**
+   * Write a binlog entry
+   * @param opcode - Operation code
+   * @param data - Data to write
+   * @returns Promise resolving to true if successful, false otherwise
+   */
+  async write(opcode, data) {
+    if (!this._isOpen) {
+      await this.open();
+    }
+    if (this._options.rotation && this._currentFileSize >= this._options.maxFileSize) {
+      await this.rotate();
+    }
+    toolkit.assert.ok(this._currentFileDescriptor, "File descriptor is null");
+    let flags = this.BINLOG_FLAG.NONE;
+    if (!Buffer.isBuffer(data)) {
+      data = tlPack.tlEncode(data);
+      flags |= this.BINLOG_FLAG.TL;
+    }
+    const dataLength = data.length;
+    const totalLength = this.BINLOG_ENTRY_HEADER_SIZE + dataLength;
+    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_ENTRY_HEADER_SIZE);
+    headerBuffer.writeUInt32LE(opcode, 0);
+    headerBuffer.writeUInt32LE(flags, 4);
+    headerBuffer.writeUInt32LE(toolkit.timestamp(), 8);
+    headerBuffer.writeUInt32LE(dataLength, 12);
+    headerBuffer.writeUInt32LE(
+      toolkit.crc32(Buffer.concat([headerBuffer.subarray(0, 16), data])) >>> 0,
+      16
+    );
+    await this._currentFileDescriptor.write(headerBuffer);
+    await this._currentFileDescriptor.write(data);
+    if (this._options.syncWrites) {
+      await this._currentFileDescriptor.sync();
+    }
+    this._currentFileSize += totalLength;
+  }
+  /**
+   * Rotate the binlog file
+   */
+  async rotate() {
+    await this.close();
+    this._currentFileIndex++;
+    await this.open();
+  }
+  /**
+   * Write the binlog header
+   */
+  async #writeBinlogHeader() {
+    toolkit.assert.ok(this._currentFileDescriptor, "File descriptor is null");
+    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);
+    headerBuffer.writeUInt32LE(this.BINLOG_MAGIC, 0);
+    headerBuffer.writeUInt32LE(this.BINLOG_VERSION, 4);
+    headerBuffer.writeUInt32LE(toolkit.timestamp(), 8);
+    headerBuffer.writeUInt32LE(0, 12);
+    await this._currentFileDescriptor.write(headerBuffer);
+    this._currentFileSize += headerBuffer.length;
+    if (this._options.syncWrites) {
+      await this._currentFileDescriptor.sync();
+    }
+  }
+  /**
+   * Read and parse all entries from a binlog file
+   * @param filename - Binlog file to read
+   * @param unsafe - Ignore broken binlog records otherwise throws error
+   * @returns Array of parsed entries
+   */
+  async readEntries(filename, unsafe) {
+    const filepath = path__default.join(this._directory, filename);
+    const fileHandle = await fs__default.promises.open(filepath, "r");
+    if (!await this.#checkBinlogHeaders(fileHandle)) {
+      if (unsafe) {
+        this._log.warn("Invalid binlog file format: " + filename);
+        return [];
+      }
+      throw new Error("Invalid binlog file format:\n" + filepath);
+    }
+    const contentSize = (await fileHandle.stat()).size - this.BINLOG_HEADER_SIZE;
+    let position = this.BINLOG_HEADER_SIZE;
+    const entries = [];
+    while (position < contentSize) {
+      const entryHeaderBuffer = Buffer.allocUnsafe(
+        this.BINLOG_ENTRY_HEADER_SIZE
+      );
+      await fileHandle.read(
+        entryHeaderBuffer,
+        0,
+        this.BINLOG_ENTRY_HEADER_SIZE,
+        position
+      );
+      const opcode = entryHeaderBuffer.readUInt32LE(0);
+      const flags = entryHeaderBuffer.readUInt32LE(4);
+      const timestamp2 = entryHeaderBuffer.readUInt32LE(8);
+      const dataLength = entryHeaderBuffer.readUInt32LE(12);
+      const crc = entryHeaderBuffer.readUInt32LE(16);
+      position += this.BINLOG_ENTRY_HEADER_SIZE;
+      let data = Buffer.allocUnsafe(dataLength);
+      await fileHandle.read(data, 0, dataLength, position);
+      const calculatedCrc = toolkit.crc32(Buffer.concat([entryHeaderBuffer.subarray(0, 16), data])) >>> 0;
+      if (calculatedCrc === crc) {
+        if (toolkit.checkBitmask(flags, this.BINLOG_FLAG.TL)) {
+          data = tlPack.tlDecode(data);
+        }
+        entries.push({
+          opcode,
+          timestamp: timestamp2,
+          data,
+          position: position - this.BINLOG_ENTRY_HEADER_SIZE
+        });
+      } else if (!unsafe) {
+        throw new Error(
+          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`
+        );
+      } else {
+        this._log.warn(
+          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`
+        );
+      }
+      position += dataLength;
+    }
+    await fileHandle.close();
+    return entries;
+  }
+  async #checkBinlogHeaders(fileHandle) {
+    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);
+    await fileHandle.read(headerBuffer, 0, this.BINLOG_HEADER_SIZE, 0);
+    const magic = headerBuffer.readUInt32LE(0);
+    const version = headerBuffer.readUInt32LE(4);
+    return magic === this.BINLOG_MAGIC && version === this.BINLOG_VERSION;
+  }
+  /**
+   * Get the current binlog file index
+   */
+  get currentFileIndex() {
+    return this._currentFileIndex;
+  }
+  /**
+   * Get current binlog file name
+   */
+  get currentFileName() {
+    return this._filePattern.replaceAll(
+      "{index}",
+      String(this._currentFileIndex)
+    );
+  }
+  /**
+   * Get current binlog directory
+   */
+  get directory() {
+    return this._directory;
+  }
+}
+function filePatternToRegex(value) {
+  return new RegExp(value.replaceAll("{index}", "(\\d+)"));
+}
+
+const DEF_OPTIONS = {
+  path: "./binlogs/log-{index}.bin",
+  maxFileSize: 104857600,
+  rotation: true,
+  syncWrites: true
+};
+function createBinlog(options) {
+  return new Binlog(toolkit.deepDefaults(options, DEF_OPTIONS));
+}
+
+exports.Binlog = Binlog;
+exports.createBinlog = createBinlog;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/Binlog.ts","../src/index.ts"],"sourcesContent":["import { tlDecode, tlEncode } from '@andrew_l/tl-pack';\nimport {\n  type Logger,\n  assert,\n  checkBitmask,\n  crc32,\n  deepClone,\n  logger,\n  timestamp,\n} from '@andrew_l/toolkit';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\n/**\n * Options for configuring the KdbBinlog\n */\nexport interface BinlogOptions {\n  /**\n   * File location to store binlog files\n   * @default './binlogs/log-{index}.bin'\n   */\n  path: string;\n\n  /**\n   * Maximum size of each binlog file before rotation (in bytes)\n   * @default 104857600\n   */\n  maxFileSize: number;\n\n  /**\n   * Whether to enable log rotation\n   * @default true\n   */\n  rotation: boolean;\n\n  /**\n   * Whether to sync writes to disk immediately\n   * @default true\n   */\n  syncWrites: boolean;\n}\n\n/**\n * Represents a single binlog entry\n */\nexport interface BinlogEntry<TData = Buffer> {\n  /**\n   * Operation code defining the type of operation\n   */\n  opcode: number;\n\n  /**\n   * Unix timestamp when the entry was created\n   */\n  timestamp: number;\n\n  /**\n   * Binary data of the entry\n   */\n  data: TData | Buffer;\n\n  /**\n   * Position in the file where this entry starts\n   */\n  position: number;\n}\n\n/**\n * TypeScript implementation of binlog system\n * Adapted from https://github.com/vk-com/kphp-kdb/blob/master/binlog/kdb-binlog-common.c\n * @group Main\n */\nexport class Binlog {\n  private _options: Required<BinlogOptions>;\n  private _filePattern: string;\n  private _directory: string;\n  private _currentFile: string | null;\n  private _currentFileDescriptor: fs.promises.FileHandle | null;\n  private _currentFileSize: number;\n  private _currentFileIndex: number;\n  private _isOpen: boolean;\n  private _log: Logger;\n\n  private readonly BINLOG_MAGIC: number = 0x4442544b;\n  private readonly BINLOG_VERSION: number = 1;\n  private readonly BINLOG_HEADER_SIZE: number = 16;\n  private readonly BINLOG_ENTRY_HEADER_SIZE: number = 20;\n  private readonly BINLOG_FLAG = Object.freeze({\n    NONE: 0,\n    TL: 1 << 0,\n  } as const);\n\n  constructor(options: BinlogOptions) {\n    this._log = logger('Binlog');\n    this._options = deepClone(options);\n    this._filePattern = path.basename(options.path);\n    this._directory = path.dirname(options.path);\n    this._currentFile = null;\n    this._currentFileDescriptor = null;\n    this._currentFileSize = 0;\n    this._currentFileIndex = 0;\n    this._isOpen = false;\n  }\n\n  /**\n   * Initialize the binlog system, ensuring directory exists and pick most recent binlog file\n   * @returns Promise resolving to true if successful, false otherwise\n   */\n  public async init(): Promise<void> {\n    await fs.promises.mkdir(this._directory, { recursive: true });\n    await this.#findLatestBinlogFile();\n  }\n\n  /**\n   * Find the latest binlog file to continue writing\n   */\n  async #findLatestBinlogFile(): Promise<void> {\n    const files = await fs.promises.readdir(this._directory);\n    const fileRegEx = filePatternToRegex(this._filePattern);\n\n    this._currentFileIndex = 0;\n\n    for (const fileName of files) {\n      const match = fileName.match(fileRegEx);\n\n      if (match) {\n        this._currentFileIndex = Math.max(\n          this._currentFileIndex,\n          parseInt(match[1], 10),\n        );\n      }\n    }\n  }\n\n  /**\n   * Open the binlog for writing\n   */\n  public async open(): Promise<void> {\n    const filePath = path.join(this._directory, this.currentFileName);\n\n    this._currentFileDescriptor = await fs.promises.open(filePath, 'a+');\n    this._currentFile = filePath;\n    this._currentFileSize = (await this._currentFileDescriptor.stat()).size;\n    this._isOpen = true;\n\n    // Write the binlog header\n    if (this._currentFileSize === 0) {\n      await this.#writeBinlogHeader();\n    } else {\n      await this.#checkBinlogHeaders(this._currentFileDescriptor);\n    }\n  }\n\n  /**\n   * Close the current binlog file\n   */\n  public async close(): Promise<void> {\n    if (!this._isOpen || !this._currentFileDescriptor) return;\n\n    // Write footer\n    await this._currentFileDescriptor.close();\n\n    this._currentFileDescriptor = null;\n    this._currentFile = null;\n    this._isOpen = false;\n  }\n\n  /**\n   * Write a binlog entry\n   * @param opcode - Operation code\n   * @param data - Data to write\n   * @returns Promise resolving to true if successful, false otherwise\n   */\n  public async write(opcode: number, data: unknown): Promise<void> {\n    if (!this._isOpen) {\n      await this.open();\n    }\n\n    // Check if we need to rotate the file\n    if (\n      this._options.rotation &&\n      this._currentFileSize >= this._options.maxFileSize\n    ) {\n      await this.rotate();\n    }\n\n    assert.ok(this._currentFileDescriptor, 'File descriptor is null');\n\n    let flags = this.BINLOG_FLAG.NONE;\n\n    if (!Buffer.isBuffer(data)) {\n      data = tlEncode(data) as Buffer;\n      flags |= this.BINLOG_FLAG.TL;\n    }\n\n    // Create entry header\n    const dataLength = (data as Buffer).length;\n    const totalLength = this.BINLOG_ENTRY_HEADER_SIZE + dataLength;\n\n    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_ENTRY_HEADER_SIZE);\n    headerBuffer.writeUInt32LE(opcode, 0);\n    headerBuffer.writeUInt32LE(flags, 4);\n    headerBuffer.writeUInt32LE(timestamp(), 8);\n    headerBuffer.writeUInt32LE(dataLength, 12);\n\n    headerBuffer.writeUInt32LE(\n      crc32(Buffer.concat([headerBuffer.subarray(0, 16), data as Buffer])) >>>\n        0,\n      16,\n    );\n\n    // Write the entry\n    await this._currentFileDescriptor.write(headerBuffer);\n    await this._currentFileDescriptor.write(data as Buffer);\n\n    if (this._options.syncWrites) {\n      await this._currentFileDescriptor.sync();\n    }\n\n    this._currentFileSize += totalLength;\n  }\n\n  /**\n   * Rotate the binlog file\n   */\n  public async rotate(): Promise<void> {\n    await this.close();\n    this._currentFileIndex++;\n    await this.open();\n  }\n\n  /**\n   * Write the binlog header\n   */\n  async #writeBinlogHeader(): Promise<void> {\n    assert.ok(this._currentFileDescriptor, 'File descriptor is null');\n\n    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);\n\n    headerBuffer.writeUInt32LE(this.BINLOG_MAGIC, 0);\n    headerBuffer.writeUInt32LE(this.BINLOG_VERSION, 4);\n    headerBuffer.writeUInt32LE(timestamp(), 8);\n    headerBuffer.writeUInt32LE(0, 12); // Reserved field\n\n    await this._currentFileDescriptor.write(headerBuffer);\n    this._currentFileSize += headerBuffer.length;\n\n    if (this._options.syncWrites) {\n      await this._currentFileDescriptor.sync();\n    }\n  }\n\n  /**\n   * Read and parse all entries from a binlog file\n   * @param filename - Binlog file to read\n   * @param unsafe - Ignore broken binlog records otherwise throws error\n   * @returns Array of parsed entries\n   */\n  public async readEntries<TData = Buffer>(\n    filename: string,\n    unsafe?: boolean,\n  ): Promise<BinlogEntry<TData>[]> {\n    const filepath = path.join(this._directory, filename);\n    const fileHandle = await fs.promises.open(filepath, 'r');\n\n    if (!(await this.#checkBinlogHeaders(fileHandle))) {\n      if (unsafe) {\n        this._log.warn('Invalid binlog file format: ' + filename);\n        return [];\n      }\n\n      throw new Error('Invalid binlog file format:\\n' + filepath);\n    }\n\n    const contentSize =\n      (await fileHandle.stat()).size - this.BINLOG_HEADER_SIZE;\n\n    let position = this.BINLOG_HEADER_SIZE;\n\n    const entries: BinlogEntry<TData>[] = [];\n\n    // Read entries until we reach the end or footer\n    while (position < contentSize) {\n      const entryHeaderBuffer = Buffer.allocUnsafe(\n        this.BINLOG_ENTRY_HEADER_SIZE,\n      );\n      await fileHandle.read(\n        entryHeaderBuffer,\n        0,\n        this.BINLOG_ENTRY_HEADER_SIZE,\n        position,\n      );\n\n      const opcode = entryHeaderBuffer.readUInt32LE(0);\n      const flags = entryHeaderBuffer.readUInt32LE(4);\n      const timestamp = entryHeaderBuffer.readUInt32LE(8);\n      const dataLength = entryHeaderBuffer.readUInt32LE(12);\n      const crc = entryHeaderBuffer.readUInt32LE(16);\n\n      position += this.BINLOG_ENTRY_HEADER_SIZE;\n\n      // Read data\n      let data = Buffer.allocUnsafe(dataLength);\n\n      await fileHandle.read(data, 0, dataLength, position);\n\n      // Verify CRC\n      const calculatedCrc =\n        crc32(Buffer.concat([entryHeaderBuffer.subarray(0, 16), data])) >>> 0;\n\n      if (calculatedCrc === crc) {\n        if (checkBitmask(flags, this.BINLOG_FLAG.TL)) {\n          data = tlDecode(data);\n        }\n\n        entries.push({\n          opcode,\n          timestamp,\n          data: data,\n          position: position - this.BINLOG_ENTRY_HEADER_SIZE,\n        });\n      } else if (!unsafe) {\n        throw new Error(\n          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`,\n        );\n      } else {\n        this._log.warn(\n          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`,\n        );\n      }\n\n      position += dataLength;\n    }\n\n    // Close file\n    await fileHandle.close();\n\n    return entries;\n  }\n\n  async #checkBinlogHeaders(\n    fileHandle: fs.promises.FileHandle,\n  ): Promise<boolean> {\n    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);\n    await fileHandle.read(headerBuffer, 0, this.BINLOG_HEADER_SIZE, 0);\n\n    const magic = headerBuffer.readUInt32LE(0);\n    const version = headerBuffer.readUInt32LE(4);\n\n    return magic === this.BINLOG_MAGIC && version === this.BINLOG_VERSION;\n  }\n\n  /**\n   * Get the current binlog file index\n   */\n  get currentFileIndex(): number {\n    return this._currentFileIndex;\n  }\n\n  /**\n   * Get current binlog file name\n   */\n  get currentFileName(): string {\n    return this._filePattern.replaceAll(\n      '{index}',\n      String(this._currentFileIndex),\n    );\n  }\n\n  /**\n   * Get current binlog directory\n   */\n  get directory(): string {\n    return this._directory;\n  }\n}\n\nfunction filePatternToRegex(value: string): RegExp {\n  return new RegExp(value.replaceAll('{index}', '(\\\\d+)'));\n}\n","import { deepDefaults } from '@andrew_l/toolkit';\nimport { Binlog, type BinlogOptions } from './Binlog.js';\n\nexport * from './Binlog.js';\n\nconst DEF_OPTIONS: BinlogOptions = {\n  path: './binlogs/log-{index}.bin',\n  maxFileSize: 104857600,\n  rotation: true,\n  syncWrites: true,\n};\n\n/**\n * Create binlog instance\n * @group Main\n */\nexport function createBinlog(options: Partial<BinlogOptions>): Binlog {\n  return new Binlog(deepDefaults(options, DEF_OPTIONS));\n}\n"],"names":["logger","deepClone","path","fs","assert","tlEncode","timestamp","crc32","checkBitmask","tlDecode","deepDefaults"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,120 @@
+/**
+ * Options for configuring the KdbBinlog
+ */
+interface BinlogOptions {
+    /**
+     * File location to store binlog files
+     * @default './binlogs/log-{index}.bin'
+     */
+    path: string;
+    /**
+     * Maximum size of each binlog file before rotation (in bytes)
+     * @default 104857600
+     */
+    maxFileSize: number;
+    /**
+     * Whether to enable log rotation
+     * @default true
+     */
+    rotation: boolean;
+    /**
+     * Whether to sync writes to disk immediately
+     * @default true
+     */
+    syncWrites: boolean;
+}
+/**
+ * Represents a single binlog entry
+ */
+interface BinlogEntry<TData = Buffer> {
+    /**
+     * Operation code defining the type of operation
+     */
+    opcode: number;
+    /**
+     * Unix timestamp when the entry was created
+     */
+    timestamp: number;
+    /**
+     * Binary data of the entry
+     */
+    data: TData | Buffer;
+    /**
+     * Position in the file where this entry starts
+     */
+    position: number;
+}
+/**
+ * TypeScript implementation of binlog system
+ * Adapted from https://github.com/vk-com/kphp-kdb/blob/master/binlog/kdb-binlog-common.c
+ * @group Main
+ */
+declare class Binlog {
+    #private;
+    private _options;
+    private _filePattern;
+    private _directory;
+    private _currentFile;
+    private _currentFileDescriptor;
+    private _currentFileSize;
+    private _currentFileIndex;
+    private _isOpen;
+    private _log;
+    private readonly BINLOG_MAGIC;
+    private readonly BINLOG_VERSION;
+    private readonly BINLOG_HEADER_SIZE;
+    private readonly BINLOG_ENTRY_HEADER_SIZE;
+    private readonly BINLOG_FLAG;
+    constructor(options: BinlogOptions);
+    /**
+     * Initialize the binlog system, ensuring directory exists and pick most recent binlog file
+     * @returns Promise resolving to true if successful, false otherwise
+     */
+    init(): Promise<void>;
+    /**
+     * Open the binlog for writing
+     */
+    open(): Promise<void>;
+    /**
+     * Close the current binlog file
+     */
+    close(): Promise<void>;
+    /**
+     * Write a binlog entry
+     * @param opcode - Operation code
+     * @param data - Data to write
+     * @returns Promise resolving to true if successful, false otherwise
+     */
+    write(opcode: number, data: unknown): Promise<void>;
+    /**
+     * Rotate the binlog file
+     */
+    rotate(): Promise<void>;
+    /**
+     * Read and parse all entries from a binlog file
+     * @param filename - Binlog file to read
+     * @param unsafe - Ignore broken binlog records otherwise throws error
+     * @returns Array of parsed entries
+     */
+    readEntries<TData = Buffer>(filename: string, unsafe?: boolean): Promise<BinlogEntry<TData>[]>;
+    /**
+     * Get the current binlog file index
+     */
+    get currentFileIndex(): number;
+    /**
+     * Get current binlog file name
+     */
+    get currentFileName(): string;
+    /**
+     * Get current binlog directory
+     */
+    get directory(): string;
+}
+
+/**
+ * Create binlog instance
+ * @group Main
+ */
+declare function createBinlog(options: Partial<BinlogOptions>): Binlog;
+
+export { Binlog, type BinlogEntry, type BinlogOptions, createBinlog };

package/dist/index.d.mts

@@ -0,0 +1,120 @@
+/**
+ * Options for configuring the KdbBinlog
+ */
+interface BinlogOptions {
+    /**
+     * File location to store binlog files
+     * @default './binlogs/log-{index}.bin'
+     */
+    path: string;
+    /**
+     * Maximum size of each binlog file before rotation (in bytes)
+     * @default 104857600
+     */
+    maxFileSize: number;
+    /**
+     * Whether to enable log rotation
+     * @default true
+     */
+    rotation: boolean;
+    /**
+     * Whether to sync writes to disk immediately
+     * @default true
+     */
+    syncWrites: boolean;
+}
+/**
+ * Represents a single binlog entry
+ */
+interface BinlogEntry<TData = Buffer> {
+    /**
+     * Operation code defining the type of operation
+     */
+    opcode: number;
+    /**
+     * Unix timestamp when the entry was created
+     */
+    timestamp: number;
+    /**
+     * Binary data of the entry
+     */
+    data: TData | Buffer;
+    /**
+     * Position in the file where this entry starts
+     */
+    position: number;
+}
+/**
+ * TypeScript implementation of binlog system
+ * Adapted from https://github.com/vk-com/kphp-kdb/blob/master/binlog/kdb-binlog-common.c
+ * @group Main
+ */
+declare class Binlog {
+    #private;
+    private _options;
+    private _filePattern;
+    private _directory;
+    private _currentFile;
+    private _currentFileDescriptor;
+    private _currentFileSize;
+    private _currentFileIndex;
+    private _isOpen;
+    private _log;
+    private readonly BINLOG_MAGIC;
+    private readonly BINLOG_VERSION;
+    private readonly BINLOG_HEADER_SIZE;
+    private readonly BINLOG_ENTRY_HEADER_SIZE;
+    private readonly BINLOG_FLAG;
+    constructor(options: BinlogOptions);
+    /**
+     * Initialize the binlog system, ensuring directory exists and pick most recent binlog file
+     * @returns Promise resolving to true if successful, false otherwise
+     */
+    init(): Promise<void>;
+    /**
+     * Open the binlog for writing
+     */
+    open(): Promise<void>;
+    /**
+     * Close the current binlog file
+     */
+    close(): Promise<void>;
+    /**
+     * Write a binlog entry
+     * @param opcode - Operation code
+     * @param data - Data to write
+     * @returns Promise resolving to true if successful, false otherwise
+     */
+    write(opcode: number, data: unknown): Promise<void>;
+    /**
+     * Rotate the binlog file
+     */
+    rotate(): Promise<void>;
+    /**
+     * Read and parse all entries from a binlog file
+     * @param filename - Binlog file to read
+     * @param unsafe - Ignore broken binlog records otherwise throws error
+     * @returns Array of parsed entries
+     */
+    readEntries<TData = Buffer>(filename: string, unsafe?: boolean): Promise<BinlogEntry<TData>[]>;
+    /**
+     * Get the current binlog file index
+     */
+    get currentFileIndex(): number;
+    /**
+     * Get current binlog file name
+     */
+    get currentFileName(): string;
+    /**
+     * Get current binlog directory
+     */
+    get directory(): string;
+}
+
+/**
+ * Create binlog instance
+ * @group Main
+ */
+declare function createBinlog(options: Partial<BinlogOptions>): Binlog;
+
+export { Binlog, type BinlogEntry, type BinlogOptions, createBinlog };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Options for configuring the KdbBinlog
+ */
+interface BinlogOptions {
+    /**
+     * File location to store binlog files
+     * @default './binlogs/log-{index}.bin'
+     */
+    path: string;
+    /**
+     * Maximum size of each binlog file before rotation (in bytes)
+     * @default 104857600
+     */
+    maxFileSize: number;
+    /**
+     * Whether to enable log rotation
+     * @default true
+     */
+    rotation: boolean;
+    /**
+     * Whether to sync writes to disk immediately
+     * @default true
+     */
+    syncWrites: boolean;
+}
+/**
+ * Represents a single binlog entry
+ */
+interface BinlogEntry<TData = Buffer> {
+    /**
+     * Operation code defining the type of operation
+     */
+    opcode: number;
+    /**
+     * Unix timestamp when the entry was created
+     */
+    timestamp: number;
+    /**
+     * Binary data of the entry
+     */
+    data: TData | Buffer;
+    /**
+     * Position in the file where this entry starts
+     */
+    position: number;
+}
+/**
+ * TypeScript implementation of binlog system
+ * Adapted from https://github.com/vk-com/kphp-kdb/blob/master/binlog/kdb-binlog-common.c
+ * @group Main
+ */
+declare class Binlog {
+    #private;
+    private _options;
+    private _filePattern;
+    private _directory;
+    private _currentFile;
+    private _currentFileDescriptor;
+    private _currentFileSize;
+    private _currentFileIndex;
+    private _isOpen;
+    private _log;
+    private readonly BINLOG_MAGIC;
+    private readonly BINLOG_VERSION;
+    private readonly BINLOG_HEADER_SIZE;
+    private readonly BINLOG_ENTRY_HEADER_SIZE;
+    private readonly BINLOG_FLAG;
+    constructor(options: BinlogOptions);
+    /**
+     * Initialize the binlog system, ensuring directory exists and pick most recent binlog file
+     * @returns Promise resolving to true if successful, false otherwise
+     */
+    init(): Promise<void>;
+    /**
+     * Open the binlog for writing
+     */
+    open(): Promise<void>;
+    /**
+     * Close the current binlog file
+     */
+    close(): Promise<void>;
+    /**
+     * Write a binlog entry
+     * @param opcode - Operation code
+     * @param data - Data to write
+     * @returns Promise resolving to true if successful, false otherwise
+     */
+    write(opcode: number, data: unknown): Promise<void>;
+    /**
+     * Rotate the binlog file
+     */
+    rotate(): Promise<void>;
+    /**
+     * Read and parse all entries from a binlog file
+     * @param filename - Binlog file to read
+     * @param unsafe - Ignore broken binlog records otherwise throws error
+     * @returns Array of parsed entries
+     */
+    readEntries<TData = Buffer>(filename: string, unsafe?: boolean): Promise<BinlogEntry<TData>[]>;
+    /**
+     * Get the current binlog file index
+     */
+    get currentFileIndex(): number;
+    /**
+     * Get current binlog file name
+     */
+    get currentFileName(): string;
+    /**
+     * Get current binlog directory
+     */
+    get directory(): string;
+}
+
+/**
+ * Create binlog instance
+ * @group Main
+ */
+declare function createBinlog(options: Partial<BinlogOptions>): Binlog;
+
+export { Binlog, type BinlogEntry, type BinlogOptions, createBinlog };

package/dist/index.mjs

@@ -0,0 +1,252 @@
+import { logger, deepClone, assert, timestamp, crc32, checkBitmask, deepDefaults } from '@andrew_l/toolkit';
+import { tlEncode, tlDecode } from '@andrew_l/tl-pack';
+import fs from 'node:fs';
+import path from 'node:path';
+
+class Binlog {
+  _options;
+  _filePattern;
+  _directory;
+  _currentFile;
+  _currentFileDescriptor;
+  _currentFileSize;
+  _currentFileIndex;
+  _isOpen;
+  _log;
+  BINLOG_MAGIC = 1145197643;
+  BINLOG_VERSION = 1;
+  BINLOG_HEADER_SIZE = 16;
+  BINLOG_ENTRY_HEADER_SIZE = 20;
+  BINLOG_FLAG = Object.freeze({
+    NONE: 0,
+    TL: 1 << 0
+  });
+  constructor(options) {
+    this._log = logger("Binlog");
+    this._options = deepClone(options);
+    this._filePattern = path.basename(options.path);
+    this._directory = path.dirname(options.path);
+    this._currentFile = null;
+    this._currentFileDescriptor = null;
+    this._currentFileSize = 0;
+    this._currentFileIndex = 0;
+    this._isOpen = false;
+  }
+  /**
+   * Initialize the binlog system, ensuring directory exists and pick most recent binlog file
+   * @returns Promise resolving to true if successful, false otherwise
+   */
+  async init() {
+    await fs.promises.mkdir(this._directory, { recursive: true });
+    await this.#findLatestBinlogFile();
+  }
+  /**
+   * Find the latest binlog file to continue writing
+   */
+  async #findLatestBinlogFile() {
+    const files = await fs.promises.readdir(this._directory);
+    const fileRegEx = filePatternToRegex(this._filePattern);
+    this._currentFileIndex = 0;
+    for (const fileName of files) {
+      const match = fileName.match(fileRegEx);
+      if (match) {
+        this._currentFileIndex = Math.max(
+          this._currentFileIndex,
+          parseInt(match[1], 10)
+        );
+      }
+    }
+  }
+  /**
+   * Open the binlog for writing
+   */
+  async open() {
+    const filePath = path.join(this._directory, this.currentFileName);
+    this._currentFileDescriptor = await fs.promises.open(filePath, "a+");
+    this._currentFile = filePath;
+    this._currentFileSize = (await this._currentFileDescriptor.stat()).size;
+    this._isOpen = true;
+    if (this._currentFileSize === 0) {
+      await this.#writeBinlogHeader();
+    } else {
+      await this.#checkBinlogHeaders(this._currentFileDescriptor);
+    }
+  }
+  /**
+   * Close the current binlog file
+   */
+  async close() {
+    if (!this._isOpen || !this._currentFileDescriptor) return;
+    await this._currentFileDescriptor.close();
+    this._currentFileDescriptor = null;
+    this._currentFile = null;
+    this._isOpen = false;
+  }
+  /**
+   * Write a binlog entry
+   * @param opcode - Operation code
+   * @param data - Data to write
+   * @returns Promise resolving to true if successful, false otherwise
+   */
+  async write(opcode, data) {
+    if (!this._isOpen) {
+      await this.open();
+    }
+    if (this._options.rotation && this._currentFileSize >= this._options.maxFileSize) {
+      await this.rotate();
+    }
+    assert.ok(this._currentFileDescriptor, "File descriptor is null");
+    let flags = this.BINLOG_FLAG.NONE;
+    if (!Buffer.isBuffer(data)) {
+      data = tlEncode(data);
+      flags |= this.BINLOG_FLAG.TL;
+    }
+    const dataLength = data.length;
+    const totalLength = this.BINLOG_ENTRY_HEADER_SIZE + dataLength;
+    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_ENTRY_HEADER_SIZE);
+    headerBuffer.writeUInt32LE(opcode, 0);
+    headerBuffer.writeUInt32LE(flags, 4);
+    headerBuffer.writeUInt32LE(timestamp(), 8);
+    headerBuffer.writeUInt32LE(dataLength, 12);
+    headerBuffer.writeUInt32LE(
+      crc32(Buffer.concat([headerBuffer.subarray(0, 16), data])) >>> 0,
+      16
+    );
+    await this._currentFileDescriptor.write(headerBuffer);
+    await this._currentFileDescriptor.write(data);
+    if (this._options.syncWrites) {
+      await this._currentFileDescriptor.sync();
+    }
+    this._currentFileSize += totalLength;
+  }
+  /**
+   * Rotate the binlog file
+   */
+  async rotate() {
+    await this.close();
+    this._currentFileIndex++;
+    await this.open();
+  }
+  /**
+   * Write the binlog header
+   */
+  async #writeBinlogHeader() {
+    assert.ok(this._currentFileDescriptor, "File descriptor is null");
+    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);
+    headerBuffer.writeUInt32LE(this.BINLOG_MAGIC, 0);
+    headerBuffer.writeUInt32LE(this.BINLOG_VERSION, 4);
+    headerBuffer.writeUInt32LE(timestamp(), 8);
+    headerBuffer.writeUInt32LE(0, 12);
+    await this._currentFileDescriptor.write(headerBuffer);
+    this._currentFileSize += headerBuffer.length;
+    if (this._options.syncWrites) {
+      await this._currentFileDescriptor.sync();
+    }
+  }
+  /**
+   * Read and parse all entries from a binlog file
+   * @param filename - Binlog file to read
+   * @param unsafe - Ignore broken binlog records otherwise throws error
+   * @returns Array of parsed entries
+   */
+  async readEntries(filename, unsafe) {
+    const filepath = path.join(this._directory, filename);
+    const fileHandle = await fs.promises.open(filepath, "r");
+    if (!await this.#checkBinlogHeaders(fileHandle)) {
+      if (unsafe) {
+        this._log.warn("Invalid binlog file format: " + filename);
+        return [];
+      }
+      throw new Error("Invalid binlog file format:\n" + filepath);
+    }
+    const contentSize = (await fileHandle.stat()).size - this.BINLOG_HEADER_SIZE;
+    let position = this.BINLOG_HEADER_SIZE;
+    const entries = [];
+    while (position < contentSize) {
+      const entryHeaderBuffer = Buffer.allocUnsafe(
+        this.BINLOG_ENTRY_HEADER_SIZE
+      );
+      await fileHandle.read(
+        entryHeaderBuffer,
+        0,
+        this.BINLOG_ENTRY_HEADER_SIZE,
+        position
+      );
+      const opcode = entryHeaderBuffer.readUInt32LE(0);
+      const flags = entryHeaderBuffer.readUInt32LE(4);
+      const timestamp2 = entryHeaderBuffer.readUInt32LE(8);
+      const dataLength = entryHeaderBuffer.readUInt32LE(12);
+      const crc = entryHeaderBuffer.readUInt32LE(16);
+      position += this.BINLOG_ENTRY_HEADER_SIZE;
+      let data = Buffer.allocUnsafe(dataLength);
+      await fileHandle.read(data, 0, dataLength, position);
+      const calculatedCrc = crc32(Buffer.concat([entryHeaderBuffer.subarray(0, 16), data])) >>> 0;
+      if (calculatedCrc === crc) {
+        if (checkBitmask(flags, this.BINLOG_FLAG.TL)) {
+          data = tlDecode(data);
+        }
+        entries.push({
+          opcode,
+          timestamp: timestamp2,
+          data,
+          position: position - this.BINLOG_ENTRY_HEADER_SIZE
+        });
+      } else if (!unsafe) {
+        throw new Error(
+          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`
+        );
+      } else {
+        this._log.warn(
+          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`
+        );
+      }
+      position += dataLength;
+    }
+    await fileHandle.close();
+    return entries;
+  }
+  async #checkBinlogHeaders(fileHandle) {
+    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);
+    await fileHandle.read(headerBuffer, 0, this.BINLOG_HEADER_SIZE, 0);
+    const magic = headerBuffer.readUInt32LE(0);
+    const version = headerBuffer.readUInt32LE(4);
+    return magic === this.BINLOG_MAGIC && version === this.BINLOG_VERSION;
+  }
+  /**
+   * Get the current binlog file index
+   */
+  get currentFileIndex() {
+    return this._currentFileIndex;
+  }
+  /**
+   * Get current binlog file name
+   */
+  get currentFileName() {
+    return this._filePattern.replaceAll(
+      "{index}",
+      String(this._currentFileIndex)
+    );
+  }
+  /**
+   * Get current binlog directory
+   */
+  get directory() {
+    return this._directory;
+  }
+}
+function filePatternToRegex(value) {
+  return new RegExp(value.replaceAll("{index}", "(\\d+)"));
+}
+
+const DEF_OPTIONS = {
+  path: "./binlogs/log-{index}.bin",
+  maxFileSize: 104857600,
+  rotation: true,
+  syncWrites: true
+};
+function createBinlog(options) {
+  return new Binlog(deepDefaults(options, DEF_OPTIONS));
+}
+
+export { Binlog, createBinlog };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":["../src/Binlog.ts","../src/index.ts"],"sourcesContent":["import { tlDecode, tlEncode } from '@andrew_l/tl-pack';\nimport {\n  type Logger,\n  assert,\n  checkBitmask,\n  crc32,\n  deepClone,\n  logger,\n  timestamp,\n} from '@andrew_l/toolkit';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\n/**\n * Options for configuring the KdbBinlog\n */\nexport interface BinlogOptions {\n  /**\n   * File location to store binlog files\n   * @default './binlogs/log-{index}.bin'\n   */\n  path: string;\n\n  /**\n   * Maximum size of each binlog file before rotation (in bytes)\n   * @default 104857600\n   */\n  maxFileSize: number;\n\n  /**\n   * Whether to enable log rotation\n   * @default true\n   */\n  rotation: boolean;\n\n  /**\n   * Whether to sync writes to disk immediately\n   * @default true\n   */\n  syncWrites: boolean;\n}\n\n/**\n * Represents a single binlog entry\n */\nexport interface BinlogEntry<TData = Buffer> {\n  /**\n   * Operation code defining the type of operation\n   */\n  opcode: number;\n\n  /**\n   * Unix timestamp when the entry was created\n   */\n  timestamp: number;\n\n  /**\n   * Binary data of the entry\n   */\n  data: TData | Buffer;\n\n  /**\n   * Position in the file where this entry starts\n   */\n  position: number;\n}\n\n/**\n * TypeScript implementation of binlog system\n * Adapted from https://github.com/vk-com/kphp-kdb/blob/master/binlog/kdb-binlog-common.c\n * @group Main\n */\nexport class Binlog {\n  private _options: Required<BinlogOptions>;\n  private _filePattern: string;\n  private _directory: string;\n  private _currentFile: string | null;\n  private _currentFileDescriptor: fs.promises.FileHandle | null;\n  private _currentFileSize: number;\n  private _currentFileIndex: number;\n  private _isOpen: boolean;\n  private _log: Logger;\n\n  private readonly BINLOG_MAGIC: number = 0x4442544b;\n  private readonly BINLOG_VERSION: number = 1;\n  private readonly BINLOG_HEADER_SIZE: number = 16;\n  private readonly BINLOG_ENTRY_HEADER_SIZE: number = 20;\n  private readonly BINLOG_FLAG = Object.freeze({\n    NONE: 0,\n    TL: 1 << 0,\n  } as const);\n\n  constructor(options: BinlogOptions) {\n    this._log = logger('Binlog');\n    this._options = deepClone(options);\n    this._filePattern = path.basename(options.path);\n    this._directory = path.dirname(options.path);\n    this._currentFile = null;\n    this._currentFileDescriptor = null;\n    this._currentFileSize = 0;\n    this._currentFileIndex = 0;\n    this._isOpen = false;\n  }\n\n  /**\n   * Initialize the binlog system, ensuring directory exists and pick most recent binlog file\n   * @returns Promise resolving to true if successful, false otherwise\n   */\n  public async init(): Promise<void> {\n    await fs.promises.mkdir(this._directory, { recursive: true });\n    await this.#findLatestBinlogFile();\n  }\n\n  /**\n   * Find the latest binlog file to continue writing\n   */\n  async #findLatestBinlogFile(): Promise<void> {\n    const files = await fs.promises.readdir(this._directory);\n    const fileRegEx = filePatternToRegex(this._filePattern);\n\n    this._currentFileIndex = 0;\n\n    for (const fileName of files) {\n      const match = fileName.match(fileRegEx);\n\n      if (match) {\n        this._currentFileIndex = Math.max(\n          this._currentFileIndex,\n          parseInt(match[1], 10),\n        );\n      }\n    }\n  }\n\n  /**\n   * Open the binlog for writing\n   */\n  public async open(): Promise<void> {\n    const filePath = path.join(this._directory, this.currentFileName);\n\n    this._currentFileDescriptor = await fs.promises.open(filePath, 'a+');\n    this._currentFile = filePath;\n    this._currentFileSize = (await this._currentFileDescriptor.stat()).size;\n    this._isOpen = true;\n\n    // Write the binlog header\n    if (this._currentFileSize === 0) {\n      await this.#writeBinlogHeader();\n    } else {\n      await this.#checkBinlogHeaders(this._currentFileDescriptor);\n    }\n  }\n\n  /**\n   * Close the current binlog file\n   */\n  public async close(): Promise<void> {\n    if (!this._isOpen || !this._currentFileDescriptor) return;\n\n    // Write footer\n    await this._currentFileDescriptor.close();\n\n    this._currentFileDescriptor = null;\n    this._currentFile = null;\n    this._isOpen = false;\n  }\n\n  /**\n   * Write a binlog entry\n   * @param opcode - Operation code\n   * @param data - Data to write\n   * @returns Promise resolving to true if successful, false otherwise\n   */\n  public async write(opcode: number, data: unknown): Promise<void> {\n    if (!this._isOpen) {\n      await this.open();\n    }\n\n    // Check if we need to rotate the file\n    if (\n      this._options.rotation &&\n      this._currentFileSize >= this._options.maxFileSize\n    ) {\n      await this.rotate();\n    }\n\n    assert.ok(this._currentFileDescriptor, 'File descriptor is null');\n\n    let flags = this.BINLOG_FLAG.NONE;\n\n    if (!Buffer.isBuffer(data)) {\n      data = tlEncode(data) as Buffer;\n      flags |= this.BINLOG_FLAG.TL;\n    }\n\n    // Create entry header\n    const dataLength = (data as Buffer).length;\n    const totalLength = this.BINLOG_ENTRY_HEADER_SIZE + dataLength;\n\n    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_ENTRY_HEADER_SIZE);\n    headerBuffer.writeUInt32LE(opcode, 0);\n    headerBuffer.writeUInt32LE(flags, 4);\n    headerBuffer.writeUInt32LE(timestamp(), 8);\n    headerBuffer.writeUInt32LE(dataLength, 12);\n\n    headerBuffer.writeUInt32LE(\n      crc32(Buffer.concat([headerBuffer.subarray(0, 16), data as Buffer])) >>>\n        0,\n      16,\n    );\n\n    // Write the entry\n    await this._currentFileDescriptor.write(headerBuffer);\n    await this._currentFileDescriptor.write(data as Buffer);\n\n    if (this._options.syncWrites) {\n      await this._currentFileDescriptor.sync();\n    }\n\n    this._currentFileSize += totalLength;\n  }\n\n  /**\n   * Rotate the binlog file\n   */\n  public async rotate(): Promise<void> {\n    await this.close();\n    this._currentFileIndex++;\n    await this.open();\n  }\n\n  /**\n   * Write the binlog header\n   */\n  async #writeBinlogHeader(): Promise<void> {\n    assert.ok(this._currentFileDescriptor, 'File descriptor is null');\n\n    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);\n\n    headerBuffer.writeUInt32LE(this.BINLOG_MAGIC, 0);\n    headerBuffer.writeUInt32LE(this.BINLOG_VERSION, 4);\n    headerBuffer.writeUInt32LE(timestamp(), 8);\n    headerBuffer.writeUInt32LE(0, 12); // Reserved field\n\n    await this._currentFileDescriptor.write(headerBuffer);\n    this._currentFileSize += headerBuffer.length;\n\n    if (this._options.syncWrites) {\n      await this._currentFileDescriptor.sync();\n    }\n  }\n\n  /**\n   * Read and parse all entries from a binlog file\n   * @param filename - Binlog file to read\n   * @param unsafe - Ignore broken binlog records otherwise throws error\n   * @returns Array of parsed entries\n   */\n  public async readEntries<TData = Buffer>(\n    filename: string,\n    unsafe?: boolean,\n  ): Promise<BinlogEntry<TData>[]> {\n    const filepath = path.join(this._directory, filename);\n    const fileHandle = await fs.promises.open(filepath, 'r');\n\n    if (!(await this.#checkBinlogHeaders(fileHandle))) {\n      if (unsafe) {\n        this._log.warn('Invalid binlog file format: ' + filename);\n        return [];\n      }\n\n      throw new Error('Invalid binlog file format:\\n' + filepath);\n    }\n\n    const contentSize =\n      (await fileHandle.stat()).size - this.BINLOG_HEADER_SIZE;\n\n    let position = this.BINLOG_HEADER_SIZE;\n\n    const entries: BinlogEntry<TData>[] = [];\n\n    // Read entries until we reach the end or footer\n    while (position < contentSize) {\n      const entryHeaderBuffer = Buffer.allocUnsafe(\n        this.BINLOG_ENTRY_HEADER_SIZE,\n      );\n      await fileHandle.read(\n        entryHeaderBuffer,\n        0,\n        this.BINLOG_ENTRY_HEADER_SIZE,\n        position,\n      );\n\n      const opcode = entryHeaderBuffer.readUInt32LE(0);\n      const flags = entryHeaderBuffer.readUInt32LE(4);\n      const timestamp = entryHeaderBuffer.readUInt32LE(8);\n      const dataLength = entryHeaderBuffer.readUInt32LE(12);\n      const crc = entryHeaderBuffer.readUInt32LE(16);\n\n      position += this.BINLOG_ENTRY_HEADER_SIZE;\n\n      // Read data\n      let data = Buffer.allocUnsafe(dataLength);\n\n      await fileHandle.read(data, 0, dataLength, position);\n\n      // Verify CRC\n      const calculatedCrc =\n        crc32(Buffer.concat([entryHeaderBuffer.subarray(0, 16), data])) >>> 0;\n\n      if (calculatedCrc === crc) {\n        if (checkBitmask(flags, this.BINLOG_FLAG.TL)) {\n          data = tlDecode(data);\n        }\n\n        entries.push({\n          opcode,\n          timestamp,\n          data: data,\n          position: position - this.BINLOG_ENTRY_HEADER_SIZE,\n        });\n      } else if (!unsafe) {\n        throw new Error(\n          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`,\n        );\n      } else {\n        this._log.warn(\n          `CRC mismatch at position ${position - this.BINLOG_ENTRY_HEADER_SIZE}`,\n        );\n      }\n\n      position += dataLength;\n    }\n\n    // Close file\n    await fileHandle.close();\n\n    return entries;\n  }\n\n  async #checkBinlogHeaders(\n    fileHandle: fs.promises.FileHandle,\n  ): Promise<boolean> {\n    const headerBuffer = Buffer.allocUnsafe(this.BINLOG_HEADER_SIZE);\n    await fileHandle.read(headerBuffer, 0, this.BINLOG_HEADER_SIZE, 0);\n\n    const magic = headerBuffer.readUInt32LE(0);\n    const version = headerBuffer.readUInt32LE(4);\n\n    return magic === this.BINLOG_MAGIC && version === this.BINLOG_VERSION;\n  }\n\n  /**\n   * Get the current binlog file index\n   */\n  get currentFileIndex(): number {\n    return this._currentFileIndex;\n  }\n\n  /**\n   * Get current binlog file name\n   */\n  get currentFileName(): string {\n    return this._filePattern.replaceAll(\n      '{index}',\n      String(this._currentFileIndex),\n    );\n  }\n\n  /**\n   * Get current binlog directory\n   */\n  get directory(): string {\n    return this._directory;\n  }\n}\n\nfunction filePatternToRegex(value: string): RegExp {\n  return new RegExp(value.replaceAll('{index}', '(\\\\d+)'));\n}\n","import { deepDefaults } from '@andrew_l/toolkit';\nimport { Binlog, type BinlogOptions } from './Binlog.js';\n\nexport * from './Binlog.js';\n\nconst DEF_OPTIONS: BinlogOptions = {\n  path: './binlogs/log-{index}.bin',\n  maxFileSize: 104857600,\n  rotation: true,\n  syncWrites: true,\n};\n\n/**\n * Create binlog instance\n * @group Main\n */\nexport function createBinlog(options: Partial<BinlogOptions>): Binlog {\n  return new Binlog(deepDefaults(options, DEF_OPTIONS));\n}\n"],"names":["timestamp"],"mappings":";;;;;AAwEO,MAAM,MAAO,CAAA;AAAA,EACV,QAAA,CAAA;AAAA,EACA,YAAA,CAAA;AAAA,EACA,UAAA,CAAA;AAAA,EACA,YAAA,CAAA;AAAA,EACA,sBAAA,CAAA;AAAA,EACA,gBAAA,CAAA;AAAA,EACA,iBAAA,CAAA;AAAA,EACA,OAAA,CAAA;AAAA,EACA,IAAA,CAAA;AAAA,EAES,YAAuB,GAAA,UAAA,CAAA;AAAA,EACvB,cAAyB,GAAA,CAAA,CAAA;AAAA,EACzB,kBAA6B,GAAA,EAAA,CAAA;AAAA,EAC7B,wBAAmC,GAAA,EAAA,CAAA;AAAA,EACnC,WAAA,GAAc,OAAO,MAAO,CAAA;AAAA,IAC3C,IAAM,EAAA,CAAA;AAAA,IACN,IAAI,CAAK,IAAA,CAAA;AAAA,GACD,CAAA,CAAA;AAAA,EAEV,YAAY,OAAwB,EAAA;AAClC,IAAK,IAAA,CAAA,IAAA,GAAO,OAAO,QAAQ,CAAA,CAAA;AAC3B,IAAK,IAAA,CAAA,QAAA,GAAW,UAAU,OAAO,CAAA,CAAA;AACjC,IAAA,IAAA,CAAK,YAAe,GAAA,IAAA,CAAK,QAAS,CAAA,OAAA,CAAQ,IAAI,CAAA,CAAA;AAC9C,IAAA,IAAA,CAAK,UAAa,GAAA,IAAA,CAAK,OAAQ,CAAA,OAAA,CAAQ,IAAI,CAAA,CAAA;AAC3C,IAAA,IAAA,CAAK,YAAe,GAAA,IAAA,CAAA;AACpB,IAAA,IAAA,CAAK,sBAAyB,GAAA,IAAA,CAAA;AAC9B,IAAA,IAAA,CAAK,gBAAmB,GAAA,CAAA,CAAA;AACxB,IAAA,IAAA,CAAK,iBAAoB,GAAA,CAAA,CAAA;AACzB,IAAA,IAAA,CAAK,OAAU,GAAA,KAAA,CAAA;AAAA,GACjB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAa,IAAsB,GAAA;AACjC,IAAM,MAAA,EAAA,CAAG,SAAS,KAAM,CAAA,IAAA,CAAK,YAAY,EAAE,SAAA,EAAW,MAAM,CAAA,CAAA;AAC5D,IAAA,MAAM,KAAK,qBAAsB,EAAA,CAAA;AAAA,GACnC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,qBAAuC,GAAA;AAC3C,IAAA,MAAM,QAAQ,MAAM,EAAA,CAAG,QAAS,CAAA,OAAA,CAAQ,KAAK,UAAU,CAAA,CAAA;AACvD,IAAM,MAAA,SAAA,GAAY,kBAAmB,CAAA,IAAA,CAAK,YAAY,CAAA,CAAA;AAEtD,IAAA,IAAA,CAAK,iBAAoB,GAAA,CAAA,CAAA;AAEzB,IAAA,KAAA,MAAW,YAAY,KAAO,EAAA;AAC5B,MAAM,MAAA,KAAA,GAAQ,QAAS,CAAA,KAAA,CAAM,SAAS,CAAA,CAAA;AAEtC,MAAA,IAAI,KAAO,EAAA;AACT,QAAA,IAAA,CAAK,oBAAoB,IAAK,CAAA,GAAA;AAAA,UAC5B,IAAK,CAAA,iBAAA;AAAA,UACL,QAAS,CAAA,KAAA,CAAM,CAAC,CAAA,EAAG,EAAE,CAAA;AAAA,SACvB,CAAA;AAAA,OACF;AAAA,KACF;AAAA,GACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAa,IAAsB,GAAA;AACjC,IAAA,MAAM,WAAW,IAAK,CAAA,IAAA,CAAK,IAAK,CAAA,UAAA,EAAY,KAAK,eAAe,CAAA,CAAA;AAEhE,IAAA,IAAA,CAAK,yBAAyB,MAAM,EAAA,CAAG,QAAS,CAAA,IAAA,CAAK,UAAU,IAAI,CAAA,CAAA;AACnE,IAAA,IAAA,CAAK,YAAe,GAAA,QAAA,CAAA;AACpB,IAAA,IAAA,CAAK,gBAAoB,GAAA,CAAA,MAAM,IAAK,CAAA,sBAAA,CAAuB,MAAQ,EAAA,IAAA,CAAA;AACnE,IAAA,IAAA,CAAK,OAAU,GAAA,IAAA,CAAA;AAGf,IAAI,IAAA,IAAA,CAAK,qBAAqB,CAAG,EAAA;AAC/B,MAAA,MAAM,KAAK,kBAAmB,EAAA,CAAA;AAAA,KACzB,MAAA;AACL,MAAM,MAAA,IAAA,CAAK,mBAAoB,CAAA,IAAA,CAAK,sBAAsB,CAAA,CAAA;AAAA,KAC5D;AAAA,GACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAa,KAAuB,GAAA;AAClC,IAAA,IAAI,CAAC,IAAA,CAAK,OAAW,IAAA,CAAC,KAAK,sBAAwB,EAAA,OAAA;AAGnD,IAAM,MAAA,IAAA,CAAK,uBAAuB,KAAM,EAAA,CAAA;AAExC,IAAA,IAAA,CAAK,sBAAyB,GAAA,IAAA,CAAA;AAC9B,IAAA,IAAA,CAAK,YAAe,GAAA,IAAA,CAAA;AACpB,IAAA,IAAA,CAAK,OAAU,GAAA,KAAA,CAAA;AAAA,GACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAa,KAAM,CAAA,MAAA,EAAgB,IAA8B,EAAA;AAC/D,IAAI,IAAA,CAAC,KAAK,OAAS,EAAA;AACjB,MAAA,MAAM,KAAK,IAAK,EAAA,CAAA;AAAA,KAClB;AAGA,IAAA,IACE,KAAK,QAAS,CAAA,QAAA,IACd,KAAK,gBAAoB,IAAA,IAAA,CAAK,SAAS,WACvC,EAAA;AACA,MAAA,MAAM,KAAK,MAAO,EAAA,CAAA;AAAA,KACpB;AAEA,IAAO,MAAA,CAAA,EAAA,CAAG,IAAK,CAAA,sBAAA,EAAwB,yBAAyB,CAAA,CAAA;AAEhE,IAAI,IAAA,KAAA,GAAQ,KAAK,WAAY,CAAA,IAAA,CAAA;AAE7B,IAAA,IAAI,CAAC,MAAA,CAAO,QAAS,CAAA,IAAI,CAAG,EAAA;AAC1B,MAAA,IAAA,GAAO,SAAS,IAAI,CAAA,CAAA;AACpB,MAAA,KAAA,IAAS,KAAK,WAAY,CAAA,EAAA,CAAA;AAAA,KAC5B;AAGA,IAAA,MAAM,aAAc,IAAgB,CAAA,MAAA,CAAA;AACpC,IAAM,MAAA,WAAA,GAAc,KAAK,wBAA2B,GAAA,UAAA,CAAA;AAEpD,IAAA,MAAM,YAAe,GAAA,MAAA,CAAO,WAAY,CAAA,IAAA,CAAK,wBAAwB,CAAA,CAAA;AACrE,IAAa,YAAA,CAAA,aAAA,CAAc,QAAQ,CAAC,CAAA,CAAA;AACpC,IAAa,YAAA,CAAA,aAAA,CAAc,OAAO,CAAC,CAAA,CAAA;AACnC,IAAa,YAAA,CAAA,aAAA,CAAc,SAAU,EAAA,EAAG,CAAC,CAAA,CAAA;AACzC,IAAa,YAAA,CAAA,aAAA,CAAc,YAAY,EAAE,CAAA,CAAA;AAEzC,IAAa,YAAA,CAAA,aAAA;AAAA,MACX,KAAM,CAAA,MAAA,CAAO,MAAO,CAAA,CAAC,YAAa,CAAA,QAAA,CAAS,CAAG,EAAA,EAAE,CAAG,EAAA,IAAc,CAAC,CAAC,CACjE,KAAA,CAAA;AAAA,MACF,EAAA;AAAA,KACF,CAAA;AAGA,IAAM,MAAA,IAAA,CAAK,sBAAuB,CAAA,KAAA,CAAM,YAAY,CAAA,CAAA;AACpD,IAAM,MAAA,IAAA,CAAK,sBAAuB,CAAA,KAAA,CAAM,IAAc,CAAA,CAAA;AAEtD,IAAI,IAAA,IAAA,CAAK,SAAS,UAAY,EAAA;AAC5B,MAAM,MAAA,IAAA,CAAK,uBAAuB,IAAK,EAAA,CAAA;AAAA,KACzC;AAEA,IAAA,IAAA,CAAK,gBAAoB,IAAA,WAAA,CAAA;AAAA,GAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAa,MAAwB,GAAA;AACnC,IAAA,MAAM,KAAK,KAAM,EAAA,CAAA;AACjB,IAAK,IAAA,CAAA,iBAAA,EAAA,CAAA;AACL,IAAA,MAAM,KAAK,IAAK,EAAA,CAAA;AAAA,GAClB;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,kBAAoC,GAAA;AACxC,IAAO,MAAA,CAAA,EAAA,CAAG,IAAK,CAAA,sBAAA,EAAwB,yBAAyB,CAAA,CAAA;AAEhE,IAAA,MAAM,YAAe,GAAA,MAAA,CAAO,WAAY,CAAA,IAAA,CAAK,kBAAkB,CAAA,CAAA;AAE/D,IAAa,YAAA,CAAA,aAAA,CAAc,IAAK,CAAA,YAAA,EAAc,CAAC,CAAA,CAAA;AAC/C,IAAa,YAAA,CAAA,aAAA,CAAc,IAAK,CAAA,cAAA,EAAgB,CAAC,CAAA,CAAA;AACjD,IAAa,YAAA,CAAA,aAAA,CAAc,SAAU,EAAA,EAAG,CAAC,CAAA,CAAA;AACzC,IAAa,YAAA,CAAA,aAAA,CAAc,GAAG,EAAE,CAAA,CAAA;AAEhC,IAAM,MAAA,IAAA,CAAK,sBAAuB,CAAA,KAAA,CAAM,YAAY,CAAA,CAAA;AACpD,IAAA,IAAA,CAAK,oBAAoB,YAAa,CAAA,MAAA,CAAA;AAEtC,IAAI,IAAA,IAAA,CAAK,SAAS,UAAY,EAAA;AAC5B,MAAM,MAAA,IAAA,CAAK,uBAAuB,IAAK,EAAA,CAAA;AAAA,KACzC;AAAA,GACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAa,WACX,CAAA,QAAA,EACA,MAC+B,EAAA;AAC/B,IAAA,MAAM,QAAW,GAAA,IAAA,CAAK,IAAK,CAAA,IAAA,CAAK,YAAY,QAAQ,CAAA,CAAA;AACpD,IAAA,MAAM,aAAa,MAAM,EAAA,CAAG,QAAS,CAAA,IAAA,CAAK,UAAU,GAAG,CAAA,CAAA;AAEvD,IAAA,IAAI,CAAE,MAAM,IAAK,CAAA,mBAAA,CAAoB,UAAU,CAAI,EAAA;AACjD,MAAA,IAAI,MAAQ,EAAA;AACV,QAAK,IAAA,CAAA,IAAA,CAAK,IAAK,CAAA,8BAAA,GAAiC,QAAQ,CAAA,CAAA;AACxD,QAAA,OAAO,EAAC,CAAA;AAAA,OACV;AAEA,MAAM,MAAA,IAAI,KAAM,CAAA,+BAAA,GAAkC,QAAQ,CAAA,CAAA;AAAA,KAC5D;AAEA,IAAA,MAAM,eACH,MAAM,UAAA,CAAW,IAAK,EAAA,EAAG,OAAO,IAAK,CAAA,kBAAA,CAAA;AAExC,IAAA,IAAI,WAAW,IAAK,CAAA,kBAAA,CAAA;AAEpB,IAAA,MAAM,UAAgC,EAAC,CAAA;AAGvC,IAAA,OAAO,WAAW,WAAa,EAAA;AAC7B,MAAA,MAAM,oBAAoB,MAAO,CAAA,WAAA;AAAA,QAC/B,IAAK,CAAA,wBAAA;AAAA,OACP,CAAA;AACA,MAAA,MAAM,UAAW,CAAA,IAAA;AAAA,QACf,iBAAA;AAAA,QACA,CAAA;AAAA,QACA,IAAK,CAAA,wBAAA;AAAA,QACL,QAAA;AAAA,OACF,CAAA;AAEA,MAAM,MAAA,MAAA,GAAS,iBAAkB,CAAA,YAAA,CAAa,CAAC,CAAA,CAAA;AAC/C,MAAM,MAAA,KAAA,GAAQ,iBAAkB,CAAA,YAAA,CAAa,CAAC,CAAA,CAAA;AAC9C,MAAMA,MAAAA,UAAAA,GAAY,iBAAkB,CAAA,YAAA,CAAa,CAAC,CAAA,CAAA;AAClD,MAAM,MAAA,UAAA,GAAa,iBAAkB,CAAA,YAAA,CAAa,EAAE,CAAA,CAAA;AACpD,MAAM,MAAA,GAAA,GAAM,iBAAkB,CAAA,YAAA,CAAa,EAAE,CAAA,CAAA;AAE7C,MAAA,QAAA,IAAY,IAAK,CAAA,wBAAA,CAAA;AAGjB,MAAI,IAAA,IAAA,GAAO,MAAO,CAAA,WAAA,CAAY,UAAU,CAAA,CAAA;AAExC,MAAA,MAAM,UAAW,CAAA,IAAA,CAAK,IAAM,EAAA,CAAA,EAAG,YAAY,QAAQ,CAAA,CAAA;AAGnD,MAAA,MAAM,aACJ,GAAA,KAAA,CAAM,MAAO,CAAA,MAAA,CAAO,CAAC,iBAAA,CAAkB,QAAS,CAAA,CAAA,EAAG,EAAE,CAAA,EAAG,IAAI,CAAC,CAAC,CAAM,KAAA,CAAA,CAAA;AAEtE,MAAA,IAAI,kBAAkB,GAAK,EAAA;AACzB,QAAA,IAAI,YAAa,CAAA,KAAA,EAAO,IAAK,CAAA,WAAA,CAAY,EAAE,CAAG,EAAA;AAC5C,UAAA,IAAA,GAAO,SAAS,IAAI,CAAA,CAAA;AAAA,SACtB;AAEA,QAAA,OAAA,CAAQ,IAAK,CAAA;AAAA,UACX,MAAA;AAAA,UACA,SAAAA,EAAAA,UAAAA;AAAA,UACA,IAAA;AAAA,UACA,QAAA,EAAU,WAAW,IAAK,CAAA,wBAAA;AAAA,SAC3B,CAAA,CAAA;AAAA,OACH,MAAA,IAAW,CAAC,MAAQ,EAAA;AAClB,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,yBAAA,EAA4B,QAAW,GAAA,IAAA,CAAK,wBAAwB,CAAA,CAAA;AAAA,SACtE,CAAA;AAAA,OACK,MAAA;AACL,QAAA,IAAA,CAAK,IAAK,CAAA,IAAA;AAAA,UACR,CAAA,yBAAA,EAA4B,QAAW,GAAA,IAAA,CAAK,wBAAwB,CAAA,CAAA;AAAA,SACtE,CAAA;AAAA,OACF;AAEA,MAAY,QAAA,IAAA,UAAA,CAAA;AAAA,KACd;AAGA,IAAA,MAAM,WAAW,KAAM,EAAA,CAAA;AAEvB,IAAO,OAAA,OAAA,CAAA;AAAA,GACT;AAAA,EAEA,MAAM,oBACJ,UACkB,EAAA;AAClB,IAAA,MAAM,YAAe,GAAA,MAAA,CAAO,WAAY,CAAA,IAAA,CAAK,kBAAkB,CAAA,CAAA;AAC/D,IAAA,MAAM,WAAW,IAAK,CAAA,YAAA,EAAc,CAAG,EAAA,IAAA,CAAK,oBAAoB,CAAC,CAAA,CAAA;AAEjE,IAAM,MAAA,KAAA,GAAQ,YAAa,CAAA,YAAA,CAAa,CAAC,CAAA,CAAA;AACzC,IAAM,MAAA,OAAA,GAAU,YAAa,CAAA,YAAA,CAAa,CAAC,CAAA,CAAA;AAE3C,IAAA,OAAO,KAAU,KAAA,IAAA,CAAK,YAAgB,IAAA,OAAA,KAAY,IAAK,CAAA,cAAA,CAAA;AAAA,GACzD;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,gBAA2B,GAAA;AAC7B,IAAA,OAAO,IAAK,CAAA,iBAAA,CAAA;AAAA,GACd;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,eAA0B,GAAA;AAC5B,IAAA,OAAO,KAAK,YAAa,CAAA,UAAA;AAAA,MACvB,SAAA;AAAA,MACA,MAAA,CAAO,KAAK,iBAAiB,CAAA;AAAA,KAC/B,CAAA;AAAA,GACF;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,SAAoB,GAAA;AACtB,IAAA,OAAO,IAAK,CAAA,UAAA,CAAA;AAAA,GACd;AACF,CAAA;AAEA,SAAS,mBAAmB,KAAuB,EAAA;AACjD,EAAA,OAAO,IAAI,MAAO,CAAA,KAAA,CAAM,UAAW,CAAA,SAAA,EAAW,QAAQ,CAAC,CAAA,CAAA;AACzD;;ACtXA,MAAM,WAA6B,GAAA;AAAA,EACjC,IAAM,EAAA,2BAAA;AAAA,EACN,WAAa,EAAA,SAAA;AAAA,EACb,QAAU,EAAA,IAAA;AAAA,EACV,UAAY,EAAA,IAAA;AACd,CAAA,CAAA;AAMO,SAAS,aAAa,OAAyC,EAAA;AACpE,EAAA,OAAO,IAAI,MAAA,CAAO,YAAa,CAAA,OAAA,EAAS,WAAW,CAAC,CAAA,CAAA;AACtD;;;;"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@andrew_l/binlog",
+  "version": "0.2.14",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "binlog"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/men232/toolkit.git",
+    "directory": "packages/binlog"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "22.10.5",
+    "typescript": "~5.6.2",
+    "unbuild": "3.0.0-rc.11",
+    "vitest": "^2.1.3"
+  },
+  "dependencies": {
+    "@andrew_l/tl-pack": "0.2.14",
+    "@andrew_l/toolkit": "0.2.14"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest watch --typecheck"
+  }
+}