@hozon/store-log 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+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,17 @@
-# Temporary Holding Version
+# @hozon/store-log
 
-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.
+Persistent structured log store with chronological queries, trace lookup, and retention.
+
+```sh
+pnpm add @hozon/store-log @hozon/db
+```
+
+```ts
+import { getLogStore, logStoreDefinition } from '@hozon/store-log'
+
+db.register(logStoreDefinition)
+const logs = await getLogStore(db)
+await logs.addLogs([])
+```
+
+See the [store reference](../../docs/reference/stores.md).

package/lib/api.d.ts

@@ -0,0 +1,5 @@
+import type { Adapter } from '@hozon/adapter';
+import type { Kysely } from 'kysely';
+import type { LogTables } from './tables.js';
+import type { LogStore } from './types.js';
+export declare function createLogStoreAPI(db: Kysely<LogTables>, adapter: Adapter): LogStore;

package/lib/api.js

@@ -0,0 +1,124 @@
+import { chunk, withKeepSet, withStoreTransaction } from '@hozon/db';
+import { categoryRange, encodeCategory } from './category.js';
+function encodeCursor(timestamp, seq) {
+    return btoa(JSON.stringify([
+        timestamp,
+        seq
+    ])).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+function decodeCursor(cursor) {
+    try {
+        const value = JSON.parse(atob(cursor.replaceAll('-', '+').replaceAll('_', '/')));
+        if (!Array.isArray(value) || value.length !== 2 || !value.every((item)=>typeof item === 'number' && Number.isFinite(item)) || !Number.isInteger(value[1])) {
+            throw new TypeError('Invalid log cursor');
+        }
+        return value;
+    } catch (cause) {
+        throw new TypeError('Invalid log cursor', {
+            cause
+        });
+    }
+}
+export function createLogStoreAPI(db, adapter) {
+    return {
+        async addLogs (logs) {
+            if (logs.length === 0) return;
+            // Validate and encode the whole input before writing any batch.
+            const rows = logs.map((log, index)=>{
+                if (log.traceID === undefined !== (log.spanID === undefined)) {
+                    throw new TypeError(`Unpaired trace/span IDs at index ${index}`);
+                }
+                return {
+                    timestamp: log.timestamp,
+                    level: log.level,
+                    category: encodeCategory(log.category),
+                    trace_id: log.traceID ?? null,
+                    span_id: log.spanID ?? null,
+                    data: adapter.encodeJSON(log)
+                };
+            });
+            await withStoreTransaction(db, async (trx)=>{
+                for (const batch of chunk(rows, 71)){
+                    await trx.insertInto('hozon_logs').values(batch).execute();
+                }
+            });
+        },
+        async queryLogs (params) {
+            if (!Number.isInteger(params.limit) || params.limit <= 0) throw new RangeError('Log limit must be a positive integer');
+            const limit = Math.min(params.limit, 1000);
+            let query = db.selectFrom('hozon_logs').select([
+                'timestamp',
+                'seq',
+                'data'
+            ]);
+            if (params.from !== undefined) query = query.where('timestamp', '>=', params.from);
+            if (params.to !== undefined) query = query.where('timestamp', '<=', params.to);
+            if (params.levels !== undefined) {
+                if (params.levels.length === 0) return {
+                    logs: []
+                };
+                query = query.where('level', 'in', [
+                    ...new Set(params.levels)
+                ]);
+            }
+            if (params.categoryPrefix !== undefined && params.categoryPrefix.length > 0) {
+                const { gte, lt } = categoryRange(params.categoryPrefix);
+                query = query.where('category', '>=', gte).where('category', '<', lt);
+            }
+            if (params.traceID !== undefined) query = query.where('trace_id', '=', params.traceID);
+            if (params.cursor !== undefined) {
+                const [timestamp, seq] = decodeCursor(params.cursor);
+                query = query.where((eb)=>eb.or([
+                        eb('timestamp', '>', timestamp),
+                        eb.and([
+                            eb('timestamp', '=', timestamp),
+                            eb('seq', '>', seq)
+                        ])
+                    ]));
+            }
+            const rows = await query.orderBy('timestamp').orderBy('seq').limit(limit + 1).execute();
+            const page = rows.slice(0, limit);
+            const last = page.at(-1);
+            return {
+                logs: page.map((row)=>row.data),
+                ...rows.length > limit && last !== undefined ? {
+                    cursor: encodeCursor(last.timestamp, last.seq)
+                } : {}
+            };
+        },
+        async getTraceLogs (traceID) {
+            const rows = await db.selectFrom('hozon_logs').select('data').where('trace_id', '=', traceID).orderBy('timestamp').orderBy('seq').execute();
+            // addLogs enforces paired IDs for every traced row.
+            return rows.map((row)=>row.data);
+        },
+        async deleteByTrace (traceIDs) {
+            if (traceIDs.length === 0) return 0;
+            return withStoreTransaction(db, async (trx)=>{
+                let count = 0;
+                for (const ids of chunk(traceIDs)){
+                    const result = await trx.deleteFrom('hozon_logs').where('trace_id', 'in', ids).executeTakeFirstOrThrow();
+                    count += Number(result.numDeletedRows);
+                }
+                return count;
+            });
+        },
+        async deleteBefore (time, params) {
+            return withStoreTransaction(db, async (trx)=>{
+                if (params?.keepTraceIDs === undefined || params.keepTraceIDs.length === 0) {
+                    const result = await trx.deleteFrom('hozon_logs').where('timestamp', '<', time).executeTakeFirstOrThrow();
+                    return Number(result.numDeletedRows);
+                }
+                return withKeepSet(trx, {
+                    table: 'hozon_keep_log',
+                    ids: params.keepTraceIDs
+                }, async (selectKeep)=>{
+                    const result = await trx.deleteFrom('hozon_logs').where('timestamp', '<', time).where((eb)=>eb.or([
+                            eb('trace_id', 'is', null),
+                            eb('trace_id', 'not in', selectKeep())
+                        ])).executeTakeFirstOrThrow();
+                    return Number(result.numDeletedRows);
+                });
+            });
+        }
+    };
+}

package/lib/category.d.ts

@@ -0,0 +1,5 @@
+export declare function encodeCategory(segments: Array<string>): string;
+export declare function categoryRange(prefix: Array<string>): {
+    gte: string;
+    lt: string;
+};

package/lib/category.js

@@ -0,0 +1,15 @@
+const SEPARATOR = '\u001f';
+export function encodeCategory(segments) {
+    for (const segment of segments){
+        if (segment.includes(SEPARATOR)) throw new TypeError('Category segment contains \\u001f');
+    }
+    return segments.length === 0 ? '' : `${segments.join(SEPARATOR)}${SEPARATOR}`;
+}
+export function categoryRange(prefix) {
+    const gte = encodeCategory(prefix);
+    // Advance the final separator, so every descendant sorts below the upper bound.
+    return {
+        gte,
+        lt: `${gte.slice(0, -1)} `
+    };
+}

package/lib/definition.d.ts

@@ -0,0 +1,6 @@
+import type { StoreDefinition, StoreProvider } from '@hozon/db';
+import type { LogTables } from './tables.js';
+import type { LogStore } from './types.js';
+export declare const LOG_STORE = "log";
+export declare const logStoreDefinition: StoreDefinition<LogTables, LogStore>;
+export declare function getLogStore(provider: StoreProvider): Promise<LogStore>;

package/lib/definition.js

@@ -0,0 +1,11 @@
+import { createLogStoreAPI } from './api.js';
+import { logStoreMigrations } from './migrations.js';
+export const LOG_STORE = 'log';
+export const logStoreDefinition = {
+    name: LOG_STORE,
+    migrations: logStoreMigrations,
+    createAPI: createLogStoreAPI
+};
+export async function getLogStore(provider) {
+    return provider.getStore(LOG_STORE);
+}

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { categoryRange, encodeCategory } from './category.js';
+export { getLogStore, LOG_STORE, logStoreDefinition } from './definition.js';
+export type { LogTables } from './tables.js';
+export type { LogLevel, LogStore, QueryLogsParams, StoredLog, TracedLog } from './types.js';
+export { isTracedLog } from './types.js';

package/lib/index.js

@@ -0,0 +1,3 @@
+export { categoryRange, encodeCategory } from './category.js';
+export { getLogStore, LOG_STORE, logStoreDefinition } from './definition.js';
+export { isTracedLog } from './types.js';

package/lib/migrations.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationContext } from '@hozon/db';
+import type { Migration } from 'kysely/migration';
+export declare function logStoreMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/migrations.js

@@ -0,0 +1,29 @@
+import { sql } from 'kysely';
+export function logStoreMigrations(ctx) {
+    return {
+        '0-init': {
+            async up (db) {
+                await db.schema.createTable('hozon_logs').addColumn('seq', ctx.types.serial, (column)=>{
+                    const primary = column.primaryKey();
+                    return ctx.kind === 'sqlite' ? primary.autoIncrement() : primary;
+                }).addColumn('timestamp', ctx.types.double, (column)=>column.notNull()).addColumn('level', ctx.types.text, (column)=>column.notNull()).addColumn('category', ctx.types.text, (column)=>{
+                    const category = column.notNull();
+                    return ctx.kind === 'postgres' ? category.modifyFront(sql`collate "C"`) : category;
+                }).addColumn('trace_id', ctx.types.text).addColumn('span_id', ctx.types.text).addColumn('data', ctx.types.json, (column)=>column.notNull()).execute();
+                await db.schema.createIndex('hozon_logs_timestamp').on('hozon_logs').column('timestamp').execute();
+                await db.schema.createIndex('hozon_logs_trace_timestamp_seq').on('hozon_logs').columns([
+                    'trace_id',
+                    'timestamp',
+                    'seq'
+                ]).execute();
+                await db.schema.createIndex('hozon_logs_level_timestamp').on('hozon_logs').columns([
+                    'level',
+                    'timestamp'
+                ]).execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('hozon_logs').execute();
+            }
+        }
+    };
+}

package/lib/tables.d.ts

@@ -0,0 +1,13 @@
+import type { ColumnType, Generated } from 'kysely';
+import type { LogLevel, StoredLog } from './types.js';
+export type LogTables = {
+    hozon_logs: {
+        seq: Generated<number>;
+        timestamp: number;
+        level: LogLevel;
+        category: string;
+        trace_id: string | null;
+        span_id: string | null;
+        data: ColumnType<StoredLog, unknown, unknown>;
+    };
+};

package/lib/tables.js

@@ -0,0 +1 @@
+export { };

package/lib/types.d.ts

@@ -0,0 +1,38 @@
+import type { JSONValue } from '@sozai/json';
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+export type StoredLog = {
+    traceID?: string;
+    spanID?: string;
+    timestamp: number;
+    level: LogLevel;
+    category: Array<string>;
+    message: string;
+    properties: Record<string, JSONValue>;
+};
+export type TracedLog = StoredLog & {
+    traceID: string;
+    spanID: string;
+};
+export declare function isTracedLog(log: StoredLog): log is TracedLog;
+export type QueryLogsParams = {
+    from?: number;
+    to?: number;
+    levels?: Array<LogLevel>;
+    categoryPrefix?: Array<string>;
+    traceID?: string;
+    limit: number;
+    cursor?: string;
+};
+export type LogStore = {
+    addLogs(logs: Array<StoredLog>): Promise<void>;
+    queryLogs(params: QueryLogsParams): Promise<{
+        logs: Array<StoredLog>;
+        cursor?: string;
+    }>;
+    getTraceLogs(traceID: string): Promise<Array<TracedLog>>;
+    deleteByTrace(traceIDs: Array<string>): Promise<number>;
+    /** An empty or omitted keepTraceIDs keeps nothing. */
+    deleteBefore(time: number, params?: {
+        keepTraceIDs?: Array<string>;
+    }): Promise<number>;
+};

package/lib/types.js

@@ -0,0 +1,3 @@
+export function isTracedLog(log) {
+    return log.traceID !== undefined && log.spanID !== undefined;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@hozon/store-log",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Portable structured log store for Hozon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/hozon.git",
+    "directory": "packages/store-log"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/adapter": "^0.1.0",
+    "@hozon/db": "^0.1.0",
+    "@sozai/json": "^0.3.0",
+    "kysely": "^0.29.6"
+  },
+  "devDependencies": {
+    "@hozon/node-sqlite": "^0.1.0",
+    "@types/node": "^26.6.4",
+    "del-cli": "^7.0.0",
+    "vitest": "5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }