Refactor: Complete Typescript Migration, Translations to English and Project Modernization by snomiao · Pull Request #1 · snomiao/WiseJSON

snomiao · 2026-03-08T14:01:33Z

Summary

Converts core library, CLI, and Explorer UI from JavaScript to TypeScript with ESM architecture
Reorganizes source code to /src directory, separates source from /dist build artifacts
Translates all comments and documentation to English
Consolidates legacy ops.js/query-ops.js into base.ts/query-base.ts as base classes
Adds comprehensive interfaces for Database, Collections, and Query logic
Integrates tsx for fast TypeScript execution and updates GitHub Actions CI/CD for Node.js 18, 20, 22

Test plan

Run pnpm build to verify TypeScript compiles without errors
Run pnpm test to verify test suite passes
Verify CLI still works after migration
Check Explorer UI loads correctly

Mirrored from upstream PR Xzdes/WiseJSON#2

🤖 Generated with Claude Code

…les to English, and 'Typescriptify' the project structure

Copilot

Pull request overview

Migrates the WiseJSON project from CommonJS JavaScript to TypeScript with an ESM-first architecture, modernizes structure into src/ + dist/, and updates tests/docs/CI accordingly.

Changes:

Replaced legacy wise-json/* CommonJS modules with typed ESM TypeScript equivalents under src/lib/* and a new package root src/index.ts.
Replaced the old JS integration test scripts with TS (tsx) runners and updated GitHub Actions to compile + run TS tests.
Modernized Explorer UI components (TS Web Components) and translated various comments/docs to English.

Reviewed changes

Copilot reviewed 105 out of 107 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
wise-json/sync/api-client.js	Removed legacy CommonJS sync API client (replaced by TS version).
wise-json/storage-utils.js	Removed legacy CommonJS storage utilities (replaced by TS version).
wise-json/logger.js	Removed legacy CommonJS logger (replaced by TS version).
wise-json/index.js	Removed legacy CommonJS main DB entry (replaced by TS version).
wise-json/errors.js	Removed legacy CommonJS custom errors (replaced by TS version).
wise-json/collection/wal-ops.js	Removed legacy WAL operations (replaced by TS version).
wise-json/collection/utils.js	Removed legacy collection utilities (replaced by TS version).
wise-json/collection/ttl.js	Removed legacy TTL utilities (replaced by TS version).
wise-json/collection/transaction-manager.js	Removed legacy transaction manager (replaced by TS version).
wise-json/collection/queue.js	Removed legacy write queue (replaced by TS version).
wise-json/collection/file-lock.js	Removed legacy file-lock helpers (replaced by TS version).
wise-json/collection/events.js	Removed legacy collection event emitter (replaced by TS version).
wise-json/collection/data-exchange.js	Removed legacy import/export helpers (replaced by TS version).
wise-json/collection/checkpoints.js	Removed legacy checkpoint controller (replaced by TS version).
wise-json/checkpoint-manager.js	Removed legacy checkpoint manager (replaced by TS version elsewhere).
test/test-index-proxy-all.ts	Added TS integration test validating package entry/proxy CRUD surface.
test/test-index-proxy-all.js	Removed legacy JS proxy test.
test/server-ready-api-all.ts	Added TS integration test for public API + error handling.
test/server-ready-api-all.js	Removed legacy JS server-ready test.
test/run-all-tests.ts	Added TS test orchestrator that runs tests via `tsx`.
test/run-all-tests.js	Removed legacy JS test orchestrator.
test/db-unique-index-all.ts	Added TS unique index constraint integration test.
test/db-unique-index-all.js	Removed legacy JS unique index test.
test/db-txn-batch-all.ts	Added TS batch ops + transaction integration test.
test/db-txn-batch-all.js	Removed legacy JS txn/batch test.
test/db-ttl-all.ts	Added TS TTL expiry/cleanup integration test.
test/db-ttl-all.js	Removed legacy JS TTL test.
test/db-functional-all.ts	Added TS “full stack” DB integration test (CRUD, TTL, export/import, recovery).
test/db-functional-all.js	Removed legacy JS functional test.
test/cli-and-api-all.js	Removed legacy JS CLI+Explorer API integration test.
test/cli-and-api-all-exclude.ts	Added TS hybrid CLI/API integration test using `tsx` for CLI/server.
test/cli-all.js	Removed legacy JS unified CLI integration test.
test/cli-all-exclude.ts	Added TS unified CLI integration test using `tsx`.
src/lib/sync/api-client.ts	Added typed HTTP(S) API client and `ApiError`.
src/lib/storage-utils.ts	Added typed storage utilities (atomic JSON writes, safe deletes, etc.).
src/lib/logger.ts	Added typed logger with ESM imports and env-driven filtering.
src/lib/index.ts	Added TypeScript `WiseJSON` class implementation under `src/lib`.
src/lib/errors.ts	Added typed custom errors with correct prototype setup for `instanceof`.
src/lib/collection/wal-ops.ts	Added typed WAL operations (read/apply/enqueue).
src/lib/collection/utils.ts	Added typed collection utilities (options defaults, filters, CSV).
src/lib/collection/ttl.ts	Added typed TTL logic + cleanup helper.
src/lib/collection/transaction-manager.ts	Added typed transaction manager with dynamic WAL manager import.
src/lib/collection/queue.ts	Added typed write queue with lock integration.
src/lib/collection/file-lock.ts	Added typed proper-lockfile wrappers.
src/lib/collection/events.ts	Added typed collection event emitter (plus new event buffering/replay).
src/lib/collection/data-exchange.ts	Added typed import/export helpers using shared CSV utility.
src/lib/cli/utils.ts	Added typed CLI argument parsing + confirmation helpers.
src/lib/cli/index.ts	Added new TS CLI entrypoint with routing + safety guard.
src/lib/cli/actions.ts	Added TS implementations for selected CLI commands.
src/index.ts	Added package-root entrypoint exporting `connect`, core classes, utilities.
pnpm-workspace.yaml	Added workspace config for built dependencies.
package.json	Switched package to ESM, added build/test tooling, updated exports/deps.
explorer/views/styles.css	Translated a few UI comments to English; minor formatting changes.
explorer/views/index.html	Minor UI text tweaks and comment cleanup.
explorer/views/components/toast-notifications.js	Removed legacy JS toast component (replaced by TS version).
explorer/views/components/toast-notificationa.ts	Added TS toast notifications Web Component.
explorer/views/components/query-builder.ts	Added TS query builder Web Component.
explorer/views/components/query-builder.js	Removed legacy JS query builder component.
explorer/views/components/json-viewer.ts	Added TS JSON viewer Web Component.
explorer/views/components/json-viewer.js	Removed legacy JS JSON viewer component.
explorer/utils.ts	Added TS utilities for ANSI color + HTML escaping.
explorer/utils.js	Removed legacy JS explorer utilities.
explorer/server.js	Removed legacy CommonJS Explorer server implementation.
explorer/seed.ts	Added TS database seed script for demo data.
explorer/seed.js	Removed legacy JS seed script.
explorer/schema-analyzer.ts	Added TS schema analyzer for Explorer graph view.
explorer/schema-analyzer.js	Removed legacy JS schema analyzer.
docs/00-introduction-and-setup.md	Removed old RU introduction doc.
docs/00 - Introduction and Setup.md	Added EN introduction doc.
cli/utils.js	Removed legacy CommonJS CLI utils (replaced by TS).
cli/index.js	Removed legacy CommonJS CLI entry (replaced by TS).
.github/workflows/nodejs.yml	Updated CI to typecheck/build TS and run `tsx` test orchestrator.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-08T14:04:50Z

  "bin": {
    "wise-json": "cli/index.js"
  },
+  "exports": {
+    ".": "./dist/lib/index.js",
+    "./cli": "./dist/cli/index.js"
+  },


The package entrypoints look inconsistent after the TS/ESM migration. bin.wise-json still points to cli/index.js (which is deleted in this PR), while exports points at ./dist/cli/index.js. This will break the installed CLI. Update bin to the built artifact path (and ensure it matches what tsc emits), e.g. pointing to ./dist/cli/index.js.

Copilot · 2026-03-08T14:04:50Z

+  "type": "module",
+  "main": "./dist/lib/index.js",
+  "types": "./dist/lib/index.d.ts",


The new public entrypoint appears to be src/index.ts (it defines/export connect and the aggregated API), but main/types/exports["."] point to ./dist/lib/index.* which likely won’t include connect and won’t match the generated dist/index.d.ts. Consider switching main/types/exports["."] to ./dist/index.js + ./dist/index.d.ts (or re-export connect from src/lib/index.ts) so consumers get the intended package-root API.

Copilot · 2026-03-08T14:04:50Z

+  "exports": {
+    ".": "./dist/lib/index.js",
+    "./cli": "./dist/cli/index.js"
+  },


The new public entrypoint appears to be src/index.ts (it defines/export connect and the aggregated API), but main/types/exports["."] point to ./dist/lib/index.* which likely won’t include connect and won’t match the generated dist/index.d.ts. Consider switching main/types/exports["."] to ./dist/index.js + ./dist/index.d.ts (or re-export connect from src/lib/index.ts) so consumers get the intended package-root API.

Copilot · 2026-03-08T14:04:50Z

+import * as fs from 'fs/promises';
+import { Collection, } from './collection/core.js';
+import { TransactionManager } from './collection/transaction-manager.js';
+import { makeAbsolutePath, validateOptions } from './collection/utils.js';


this.options is being force-cast to Required<CollectionOptions> instead of being validated/defaulted (and validateOptions is imported but not used). This can drop required defaults like idGenerator, WAL/checkpoint thresholds, and logger, and can cause runtime undefined access later. Recommend setting this.options = validateOptions(options) (or equivalent) to preserve defaults and satisfy the Required<CollectionOptions> contract.

Copilot · 2026-03-08T14:04:50Z

+  constructor(dbRootPath: string = DEFAULT_PATH, options: Partial<CollectionOptions> = {}) {
+    this.dbRootPath = makeAbsolutePath(dbRootPath);
+    // Use the utility to fill in defaults
+    this.options = options as unknown as Required<CollectionOptions>;


this.options is being force-cast to Required<CollectionOptions> instead of being validated/defaulted (and validateOptions is imported but not used). This can drop required defaults like idGenerator, WAL/checkpoint thresholds, and logger, and can cause runtime undefined access later. Recommend setting this.options = validateOptions(options) (or equivalent) to preserve defaults and satisfy the Required<CollectionOptions> contract.

Suggested change

this.options = options as unknown as Required<CollectionOptions>;

this.options = validateOptions(options);

Copilot · 2026-03-08T14:04:52Z

+ * and infer relationships between different data sets.
+ */
+
+import { Collection, WiseJSON } from "../src/index";


This import is likely to fail under ESM/tsx because it has no file extension and doesn’t match the repo’s other ESM-style imports (e.g. ../src/index.js). Use an explicit ESM-resolvable specifier (and ensure it points at the correct runtime entrypoint, src/index.ts compiled to dist/index.js).

Suggested change

import { Collection, WiseJSON } from "../src/index";

import { Collection, WiseJSON } from "../src/index.js";

Copilot · 2026-03-08T14:04:53Z

+// Include the library
+const WiseJSON = require('wise-json-db');
+const path = require('path');
+
+async function main() {
+// 1. Specify the path where the database will be stored.
+const dbPath = path.resolve(__dirname, 'myAppData');
+
+// 2. Create or open a DB instance and wait for it to initialize.
+const db = new WiseJSON(dbPath);
+await db.init();
+
+// 3. Get (or create) the 'users' collection and wait for it to be ready.
+const users = await db.collection('users');
+await users.initPromise;
+
+// To keep the example clean, we'll clear the collection before starting.
+await users.clear();
+
+// 4. Insert documents.
+await users.insert({ name: 'Alice', age: 30, city: 'New York' });
+await users.insertMany([
+{ name: 'Bob', age: 25, city: 'London' },
+{ name: 'Charlie', age: 35, city: 'New York' }
+]);
+console.log(`After inserting a document into the collection, ${await users.count()}.`);


The package is now "type": "module" and appears to expose an ESM-first API (including connect). The Quick Start still uses require(...), which will fail in ESM-only installs. Update the docs to use import syntax (or document both ESM and CommonJS consumption patterns if you intend to support CJS via dual exports).

Suggested change

// Include the library

const WiseJSON = require('wise-json-db');

const path = require('path');

async function main() {

// 1. Specify the path where the database will be stored.

const dbPath = path.resolve(__dirname, 'myAppData');

// 2. Create or open a DB instance and wait for it to initialize.

const db = new WiseJSON(dbPath);

await db.init();

// 3. Get (or create) the 'users' collection and wait for it to be ready.

const users = await db.collection('users');

await users.initPromise;

// To keep the example clean, we'll clear the collection before starting.

await users.clear();

// 4. Insert documents.

await users.insert({ name: 'Alice', age: 30, city: 'New York' });

await users.insertMany([

{ name: 'Bob', age: 25, city: 'London' },

{ name: 'Charlie', age: 35, city: 'New York' }

]);

console.log(`After inserting a document into the collection, ${await users.count()}.`);

// Include the library (ESM)

import WiseJSON from 'wise-json-db';

import path from 'path';

async function main() {

// 1. Specify the path where the database will be stored.

const dbPath = path.resolve(process.cwd(), 'myAppData');

// 2. Create or open a DB instance and wait for it to initialize.

const db = new WiseJSON(dbPath);

await db.init();

// 3. Get (or create) the 'users' collection and wait for it to be ready.

const users = await db.collection('users');

await users.initPromise;

// To keep the example clean, we'll clear the collection before starting.

await users.clear();

// 4. Insert documents.

await users.insert({ name: 'Alice', age: 30, city: 'New York' });

await users.insertMany([

{ name: 'Bob', age: 25, city: 'London' },

{ name: 'Charlie', age: 35, city: 'New York' }

]);

console.log(`After inserting a document into the collection, ${await users.count()}.`);

Copilot · 2026-03-08T14:04:53Z

+ * Execution pipeline: parses arguments, initializes DB, and routes to action handlers.
+ */
+async function main(): Promise<void> {
+  console.log("CLI ARGS, ", process.argv)


This looks like leftover debug output and will pollute CLI stdout (breaking pipes/scripts/tests that expect clean JSON output). Remove it or gate it behind an explicit debug flag/env var.

Suggested change

console.log("CLI ARGS, ", process.argv)

Copilot · 2026-03-08T14:04:53Z

@@ -0,0 +1,108 @@
+/**
+ * test/test-index-proxy-all.test.ts


The header comment filename doesn’t match the actual file name (test-index-proxy-all.ts), and __dirname/__filename are computed but not used in this test. Consider removing unused ESM compatibility boilerplate and/or fixing the header comment to reduce noise.

Copilot · 2026-03-08T14:04:53Z

+import { fileURLToPath } from 'url';
+
+// --- ESM Compatibility ---
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);


The header comment filename doesn’t match the actual file name (test-index-proxy-all.ts), and __dirname/__filename are computed but not used in this test. Consider removing unused ESM compatibility boilerplate and/or fixing the header comment to reduce noise.

Refactor: Convert to TypeScript, ESM, translate ALL COMMENTS & DOC fi…

4622888

…les to English, and 'Typescriptify' the project structure

Copilot AI review requested due to automatic review settings March 8, 2026 14:01

snomiao merged commit b93dc59 into master Mar 8, 2026
0 of 3 checks passed

Copilot AI reviewed Mar 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor: Complete Typescript Migration, Translations to English and Project Modernization#1

Refactor: Complete Typescript Migration, Translations to English and Project Modernization#1
snomiao merged 1 commit into
masterfrom
feature/typescript-migration

snomiao commented Mar 8, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	this.options = options as unknown as Required<CollectionOptions>;
	this.options = validateOptions(options);

	import { Collection, WiseJSON } from "../src/index";
	import { Collection, WiseJSON } from "../src/index.js";

Conversation

snomiao commented Mar 8, 2026

Summary

Test plan

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants