@hlw2326/jsonl 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hlw2326
+
+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

@@ -1,3 +1,126 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @hlw2326/jsonl
+
+轻量、零运行时依赖的 JSONL 文件读写包。自动处理逐行解析、空行、换行和文件写入，不包含数据库、日志权限或业务字段校验。
+
+支持 Node.js 22+、ESM、CommonJS 和 TypeScript。npm 包仅包含编译后的 JavaScript、类型声明和文档，不发布 `src`。
+
+## 安装
+
+```sh
+pnpm add @hlw2326/jsonl
+```
+
+## 使用
+
+```ts
+import { Jsonl } from '@hlw2326/jsonl'
+
+interface Log {
+  appId: string
+  message: string
+}
+
+const logs = new Jsonl<Log>('./data/logs.jsonl')
+
+await logs.append({ appId: 'app-a', message: '已启动' })
+await logs.append([
+  { appId: 'app-a', message: '已连接' },
+  { appId: 'app-b', message: '已启动' }
+])
+
+const records = await logs.read()
+const mine = records.filter(record => record.appId === 'app-a')
+
+const removed = await logs.remove(record => record.appId === 'app-a')
+await logs.write(mine)
+await logs.clear()
+```
+
+CommonJS：
+
+```js
+const { Jsonl } = require('@hlw2326/jsonl')
+
+const file = new Jsonl('./data/records.jsonl')
+```
+
+## API
+
+### `new Jsonl<T>(file, { strict?: boolean })`
+
+`file` 相对当前工作目录解析。默认 `strict: false`，读取时跳过 JSON 语法损坏的行；空行始终忽略，支持 UTF-8 BOM、CRLF 和末尾没有换行的文件。
+
+```ts
+const file = new Jsonl<Log>('./logs.jsonl', { strict: true })
+```
+
+严格模式遇到损坏行时抛出包含文件路径及行号的 `SyntaxError`。它只检查 JSON 语法，不检查业务字段；泛型 `T` 只是类型提示，外部不可信数据仍需自行校验。
+
+### `read(): Promise<T[]>`
+
+读取全部有效记录；文件不存在时返回 `[]`，其他文件系统错误正常抛出。
+
+### `append(record | records): Promise<void>`
+
+追加一条或多条记录，自动创建父目录，并补齐已有文件末尾缺失的换行。空数组不写入。
+
+数组参数表示多条记录；如果记录本身就是数组，外面再包一层：
+
+```ts
+const arrays = new Jsonl<number[]>('./arrays.jsonl')
+await arrays.append([[1, 2, 3]])
+```
+
+### `write(records): Promise<void>`
+
+用新记录替换文件。先完整序列化，再写入同目录临时文件，最后重命名替换目标。
+
+### `remove(predicate): Promise<number>`
+
+删除符合条件的记录，返回删除数量。默认模式保留原文件中无法解析的行；严格模式遇到损坏行时拒绝操作，不修改原文件。没有匹配记录时不重写文件。
+
+### `clear(): Promise<void>`
+
+清空全部内容，文件保留；文件不存在时创建空文件。
+
+## 行为边界
+
+- 所有记录按标准 `JSON.stringify` 规则保存，`undefined`、函数、Symbol 等无法作为顶层 JSON 值写入；循环引用、BigInt 等序列化错误会拒绝本次写入。批量写入先完成全部序列化，避免因后续记录无法序列化而只写入部分数据。
+- 同一模块实例内、同一绝对路径的操作按调用顺序串行执行，包括不同 `Jsonl` 对象；一次操作失败不会阻塞后续操作。
+- 不提供跨进程、Worker、不同模块副本或符号链接别名之间的文件锁；请让一个进程统一管理同一文件。
+- `write`、`remove`、`clear` 使用临时文件替换，替换前失败会保留旧文件；`append` 是直接追加，底层写入失败可能留下部分数据。这里不承诺断电持久性，也不执行 `fsync`。
+- `read`、`remove` 会读取整个文件，适合按天分文件的日志及中小型 JSONL 数据，不是大文件流式查询引擎。
+- 包不自动轮转文件、不判断应用身份，也不管理日志保留时间。
+
+## 开发与发布
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test
+```
+
+`pnpm test` 会先编译。`pnpm build` 生成：
+
+```text
+dist/
+├── esm/
+│   ├── index.js
+│   └── index.d.ts
+└── cjs/
+    ├── index.js
+    ├── index.d.ts
+    └── package.json
+```
+
+发布前检查实际包内容，再发布：
+
+```sh
+npm pack --dry-run
+npm login
+npm publish --access public
+```
+
+`prepack` 自动执行构建和测试，`files` 白名单仅包含 `dist`、`README.md`、`LICENSE`；`package.json` 由 npm 自动包含。源码、测试、构建脚本、配置和 source map 均不发布。
+
+发布账号必须拥有 `@hlw2326` 作用域的发布权限。再次发布前需要修改版本号；具体双因素认证或令牌要求以 npm 提示为准。

package/dist/cjs/index.d.ts

@@ -0,0 +1,15 @@
+export declare class Jsonl<T = unknown> {
+    private readonly file;
+    private readonly strict;
+    constructor(file: string, options?: {
+        strict?: boolean;
+    });
+    read(): Promise<T[]>;
+    /** 数组参数表示多条记录；数组本身作为一条记录时使用 append([array])。 */
+    append(value: T | readonly T[]): Promise<void>;
+    write(records: readonly T[]): Promise<void>;
+    remove(predicate: (record: T) => boolean): Promise<number>;
+    clear(): Promise<void>;
+    private parse;
+    private replace;
+}

package/dist/cjs/index.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Jsonl = void 0;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const queues = new Map();
+function enqueue(file, operation) {
+    const result = (queues.get(file) ?? Promise.resolve()).then(operation);
+    const tail = result.then(() => { }, () => { });
+    queues.set(file, tail);
+    void tail.then(() => {
+        if (queues.get(file) === tail)
+            queues.delete(file);
+    });
+    return result;
+}
+async function load(file) {
+    try {
+        return await (0, promises_1.readFile)(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+function serialize(records) {
+    const lines = records.map((record) => {
+        const line = JSON.stringify(record);
+        if (line === undefined)
+            throw new TypeError('Record cannot be serialized as JSON');
+        return line;
+    });
+    return lines.length ? `${lines.join('\n')}\n` : '';
+}
+class Jsonl {
+    file;
+    strict;
+    constructor(file, options) {
+        this.file = (0, node_path_1.resolve)(file);
+        this.strict = options?.strict ?? false;
+    }
+    read() {
+        return enqueue(this.file, async () => {
+            const lines = (await load(this.file)).split(/(?<=\n)/);
+            const records = [];
+            for (const [index, line] of lines.entries()) {
+                const parsed = this.parse(line, index);
+                if (parsed)
+                    records.push(parsed.value);
+            }
+            return records;
+        });
+    }
+    /** 数组参数表示多条记录；数组本身作为一条记录时使用 append([array])。 */
+    append(value) {
+        return enqueue(this.file, async () => {
+            const data = serialize(Array.isArray(value) ? value : [value]);
+            if (!data)
+                return;
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.file), { recursive: true });
+            const file = await (0, promises_1.open)(this.file, 'a+');
+            try {
+                const { size } = await file.stat();
+                const last = Buffer.alloc(1);
+                if (size)
+                    await file.read(last, 0, 1, size - 1);
+                const separator = size && last[0] !== 10 ? '\n' : '';
+                await file.writeFile(separator + data, 'utf8');
+            }
+            finally {
+                await file.close();
+            }
+        });
+    }
+    write(records) {
+        return enqueue(this.file, async () => {
+            await this.replace(serialize(records));
+        });
+    }
+    remove(predicate) {
+        return enqueue(this.file, async () => {
+            const lines = (await load(this.file)).split(/(?<=\n)/);
+            let removed = 0;
+            const remaining = lines.filter((line, index) => {
+                const parsed = this.parse(line, index);
+                if (!parsed || !predicate(parsed.value))
+                    return true;
+                removed++;
+                return false;
+            });
+            if (removed)
+                await this.replace(remaining.join(''));
+            return removed;
+        });
+    }
+    clear() {
+        return enqueue(this.file, async () => {
+            await this.replace('');
+        });
+    }
+    parse(line, index) {
+        const text = line.trim();
+        if (!text)
+            return undefined;
+        try {
+            return { value: JSON.parse(text) };
+        }
+        catch (error) {
+            if (this.strict) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new SyntaxError(`${this.file}:${index + 1}: Invalid JSON: ${detail}`, {
+                    cause: error,
+                });
+            }
+            return undefined;
+        }
+    }
+    async replace(data) {
+        const directory = (0, node_path_1.dirname)(this.file);
+        await (0, promises_1.mkdir)(directory, { recursive: true });
+        const temporary = (0, node_path_1.join)(directory, `.jsonl-${(0, node_crypto_1.randomUUID)()}.tmp`);
+        try {
+            await (0, promises_1.writeFile)(temporary, data, { encoding: 'utf8', flag: 'wx' });
+            await (0, promises_1.rename)(temporary, this.file);
+        }
+        finally {
+            await (0, promises_1.unlink)(temporary).catch(() => { });
+        }
+    }
+}
+exports.Jsonl = Jsonl;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,15 @@
+export declare class Jsonl<T = unknown> {
+    private readonly file;
+    private readonly strict;
+    constructor(file: string, options?: {
+        strict?: boolean;
+    });
+    read(): Promise<T[]>;
+    /** 数组参数表示多条记录；数组本身作为一条记录时使用 append([array])。 */
+    append(value: T | readonly T[]): Promise<void>;
+    write(records: readonly T[]): Promise<void>;
+    remove(predicate: (record: T) => boolean): Promise<number>;
+    clear(): Promise<void>;
+    private parse;
+    private replace;
+}

package/dist/esm/index.js

@@ -0,0 +1,129 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+const queues = new Map();
+function enqueue(file, operation) {
+    const result = (queues.get(file) ?? Promise.resolve()).then(operation);
+    const tail = result.then(() => { }, () => { });
+    queues.set(file, tail);
+    void tail.then(() => {
+        if (queues.get(file) === tail)
+            queues.delete(file);
+    });
+    return result;
+}
+async function load(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+function serialize(records) {
+    const lines = records.map((record) => {
+        const line = JSON.stringify(record);
+        if (line === undefined)
+            throw new TypeError('Record cannot be serialized as JSON');
+        return line;
+    });
+    return lines.length ? `${lines.join('\n')}\n` : '';
+}
+export class Jsonl {
+    file;
+    strict;
+    constructor(file, options) {
+        this.file = resolve(file);
+        this.strict = options?.strict ?? false;
+    }
+    read() {
+        return enqueue(this.file, async () => {
+            const lines = (await load(this.file)).split(/(?<=\n)/);
+            const records = [];
+            for (const [index, line] of lines.entries()) {
+                const parsed = this.parse(line, index);
+                if (parsed)
+                    records.push(parsed.value);
+            }
+            return records;
+        });
+    }
+    /** 数组参数表示多条记录；数组本身作为一条记录时使用 append([array])。 */
+    append(value) {
+        return enqueue(this.file, async () => {
+            const data = serialize(Array.isArray(value) ? value : [value]);
+            if (!data)
+                return;
+            await mkdir(dirname(this.file), { recursive: true });
+            const file = await open(this.file, 'a+');
+            try {
+                const { size } = await file.stat();
+                const last = Buffer.alloc(1);
+                if (size)
+                    await file.read(last, 0, 1, size - 1);
+                const separator = size && last[0] !== 10 ? '\n' : '';
+                await file.writeFile(separator + data, 'utf8');
+            }
+            finally {
+                await file.close();
+            }
+        });
+    }
+    write(records) {
+        return enqueue(this.file, async () => {
+            await this.replace(serialize(records));
+        });
+    }
+    remove(predicate) {
+        return enqueue(this.file, async () => {
+            const lines = (await load(this.file)).split(/(?<=\n)/);
+            let removed = 0;
+            const remaining = lines.filter((line, index) => {
+                const parsed = this.parse(line, index);
+                if (!parsed || !predicate(parsed.value))
+                    return true;
+                removed++;
+                return false;
+            });
+            if (removed)
+                await this.replace(remaining.join(''));
+            return removed;
+        });
+    }
+    clear() {
+        return enqueue(this.file, async () => {
+            await this.replace('');
+        });
+    }
+    parse(line, index) {
+        const text = line.trim();
+        if (!text)
+            return undefined;
+        try {
+            return { value: JSON.parse(text) };
+        }
+        catch (error) {
+            if (this.strict) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new SyntaxError(`${this.file}:${index + 1}: Invalid JSON: ${detail}`, {
+                    cause: error,
+                });
+            }
+            return undefined;
+        }
+    }
+    async replace(data) {
+        const directory = dirname(this.file);
+        await mkdir(directory, { recursive: true });
+        const temporary = join(directory, `.jsonl-${randomUUID()}.tmp`);
+        try {
+            await writeFile(temporary, data, { encoding: 'utf8', flag: 'wx' });
+            await rename(temporary, this.file);
+        }
+        finally {
+            await unlink(temporary).catch(() => { });
+        }
+    }
+}

package/package.json

@@ -1,6 +1,51 @@
-{
-  "name": "@hlw2326/jsonl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@hlw2326/jsonl",
+  "version": "0.1.0",
+  "description": "Small, dependency-free JSONL file storage for Node.js",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node scripts/build.mjs && node --test tests/jsonl.test.mjs tests/package.test.mjs",
+    "prepack": "npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "jsonl",
+    "ndjson",
+    "json-lines",
+    "file-storage",
+    "typescript"
+  ],
+  "author": "hlw2326",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}