refactor: restructure file tree & add .npmignore

Author: zxch3n

README.md

@@ -93,16 +93,19 @@ Example (Node 18+):
 import { LoroWebsocketClient } from "loro-websocket/client";
 import { EloLoroAdaptor } from "loro-adaptors";
 import { WebSocket } from "ws";
-(globalThis as any).WebSocket = WebSocket as unknown as typeof globalThis.WebSocket;
+(globalThis as any).WebSocket =
+  WebSocket as unknown as typeof globalThis.WebSocket;
 
 const key = new Uint8Array([
-  0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,
-  16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,
+  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21,
+  22, 23, 24, 25, 26, 27, 28, 29, 30, 31,
 ]);
 
 const client = new LoroWebsocketClient({ url: "ws://localhost:8787" });
 await client.waitConnected();
-const adaptor = new EloLoroAdaptor({ getPrivateKey: async () => ({ keyId: "k1", key }) });
+const adaptor = new EloLoroAdaptor({
+  getPrivateKey: async () => ({ keyId: "k1", key }),
+});
 const room = await client.join({ roomId: "elo-room", crdtAdaptor: adaptor });
 
 // Edit the encrypted doc
@@ -114,6 +117,7 @@ await room.destroy();
 ```
 
 Notes:
+
 - Use a unique, non‑repeating 12‑byte IV per encryption for security (the adaptor accepts an optional `ivFactory()` for testing); the examples may fix IVs for determinism in tests only.
 - Keys and key agreement are application‑provided and out of scope.
 
@@ -128,14 +132,16 @@ pnpm run test:cross-lang
 ```
 
 This will:
+
 - Run the Rust cross‑lang e2e test (`rust/loro-websocket-server/tests/elo_cross_lang.rs`) with logs.
 - Spawn thin TS test-wrappers via `pnpm exec tsx`:
-  - `packages/loro-websocket/src/test-wrappers/start-simple-server.ts`
-  - `packages/loro-websocket/src/test-wrappers/send-elo-normative.ts`
-  - `packages/loro-websocket/src/test-wrappers/recv-elo-doc.ts`
+  - `packages/loro-websocket/test-wrappers/start-simple-server.ts`
+  - `packages/loro-websocket/test-wrappers/send-elo-normative.ts`
+  - `packages/loro-websocket/test-wrappers/recv-elo-doc.ts`
 - Use the Rust example `rust/loro-websocket-client/examples/elo_index_client.rs` which encrypts/decrypts real `%ELO` containers.
 
 Requirements:
+
 - Node 18+, pnpm (or npx fallback), Rust toolchain.
 - For CI stability, you can run with a single test thread:
   `cargo test -p loro-websocket-server --test elo_cross_lang -- --ignored --nocapture --test-threads=1`.

packages/loro-adaptors/.npmignore

@@ -0,0 +1,55 @@
+# Ignore development artifacts and configs. Keep built output (and TS sources if desired) via package.json "files".
+# TODO: REVIEW: This package currently whitelists "src/**/*" in package.json.
+# NPM's "files" allowlist overrides .npmignore exclusions; thus test files under src will still be published.
+# If you want to exclude tests from the published tarball, update package.json "files" to omit tests (e.g. only "dist").
+
+# VCS / OS
+.git
+.gitignore
+.gitattributes
+.DS_Store
+.idea/
+.vscode/
+
+# Package manager locks
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Tests (not shipped)
+__tests__/
+test/
+tests/
+*.test.*
+*.spec.*
+
+# Coverage / reports
+coverage/
+.nyc_output/
+
+# Build/tooling configs
+tsconfig.json
+tsconfig.*.json
+tsdown.config.ts
+vitest.config.ts
+jest.config.*
+rollup.config.*
+vite.config.*
+babel.config.*
+postcss.config.*
+tailwind.config.*
+
+# Local scripts and examples
+scripts/
+examples/
+demo/
+
+# Project docs not needed in tarball
+AGENTS.md
+PLAN.md

…kages/loro-adaptors/src/adaptors.test.ts …ges/loro-adaptors/tests/adaptors.test.tspackages/loro-adaptors/src/adaptors.test.ts renamed to packages/loro-adaptors/tests/adaptors.test.ts packages/loro-adaptors/src/adaptors.test.ts renamed to packages/loro-adaptors/tests/adaptors.test.ts

@@ -4,7 +4,7 @@ import {
   LoroAdaptor,
   LoroEphemeralAdaptor,
   createLoroAdaptor,
-} from "./adaptors";
+} from "../src/adaptors";
 import { CrdtType, JoinResponseOk, MessageType } from "loro-protocol";
 
 describe("LoroAdaptor", () => {

…es/loro-adaptors/src/elo-adaptor.test.ts …/loro-adaptors/tests/elo-adaptor.test.tspackages/loro-adaptors/src/elo-adaptor.test.ts renamed to packages/loro-adaptors/tests/elo-adaptor.test.ts packages/loro-adaptors/src/elo-adaptor.test.ts renamed to packages/loro-adaptors/tests/elo-adaptor.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { LoroDoc } from "loro-crdt";
-import { EloLoroAdaptor } from "./adaptors";
+import { EloLoroAdaptor } from "../src/adaptors";
 import { CrdtType, MessageType } from "loro-protocol";
 import { parseEloRecordHeader, decodeEloContainer } from "loro-protocol";
 import { encryptDeltaSpan, encodeEloContainer } from "loro-protocol";

packages/loro-protocol/.npmignore

@@ -0,0 +1,52 @@
+# Ignore development artifacts and configs. Publish only built output via package.json "files".
+
+# VCS / OS
+.git
+.gitignore
+.gitattributes
+.DS_Store
+.idea/
+.vscode/
+
+# Package manager locks
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Tests (not shipped)
+__tests__/
+test/
+tests/
+*.test.*
+*.spec.*
+
+# Coverage / reports
+coverage/
+.nyc_output/
+
+# Build/tooling configs
+tsconfig.json
+tsconfig.*.json
+tsdown.config.ts
+vitest.config.ts
+jest.config.*
+rollup.config.*
+vite.config.*
+babel.config.*
+postcss.config.*
+tailwind.config.*
+
+# Local scripts and examples
+scripts/
+examples/
+demo/
+
+# Project docs not needed in tarball
+AGENTS.md
+PLAN.md

…__snapshots__/encoding.snap.test.ts.snap …__snapshots__/encoding.snap.test.ts.snappackages/loro-protocol/src/__snapshots__/encoding.snap.test.ts.snap renamed to packages/loro-protocol/tests/__snapshots__/encoding.snap.test.ts.snap packages/loro-protocol/src/__snapshots__/encoding.snap.test.ts.snap renamed to packages/loro-protocol/tests/__snapshots__/encoding.snap.test.ts.snap

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { BytesReader, BytesWriter } from "./bytes";
+import { BytesReader, BytesWriter } from "../src/bytes";
 
 describe("BytesWriter/BytesReader", () => {
   it("round-trips ULEB128 for typical bounds", () => {

packages/loro-protocol/src/bytes.test.ts …ckages/loro-protocol/tests/bytes.test.tspackages/loro-protocol/src/bytes.test.ts renamed to packages/loro-protocol/tests/bytes.test.ts packages/loro-protocol/src/bytes.test.ts renamed to packages/loro-protocol/tests/bytes.test.ts

@@ -6,8 +6,8 @@ import {
   encryptDeltaSpan,
   encryptSnapshot,
   parseEloRecordHeader,
-} from "./e2ee";
-import { bytesToHex, hexToBytes } from "./protocol";
+} from "../src/e2ee";
+import { bytesToHex, hexToBytes } from "../src/protocol";
 
 describe("%ELO container codec", () => {
   it("encodes and decodes container", () => {
@@ -29,7 +29,11 @@ describe("%ELO record header parsing", () => {
     const iv = hexToBytes("0x86bcad09d5e7e3d70503a57e");
     const plaintext = hexToBytes("0x01026869");
     const meta = { peerId, start: 1, end: 3, keyId: "k1", iv };
-    const { record, headerBytes } = await encryptDeltaSpan(plaintext, meta, key);
+    const { record, headerBytes } = await encryptDeltaSpan(
+      plaintext,
+      meta,
+      key
+    );
     const parsed = parseEloRecordHeader(record);
     expect(parsed.kind).toBe(EloRecordKind.DeltaSpan);
     expect(bytesToHex(parsed.headerBytes)).toEqual(bytesToHex(headerBytes));
@@ -78,18 +82,18 @@ describe("%ELO Snapshot header vv sorting", () => {
       { peerId: hexToBytes("0x01ff"), counter: 9 },
       { peerId: hexToBytes("0x01"), counter: 7 },
     ];
-    const { record } = await encryptSnapshot(plaintext, { vv: vvUnsorted, keyId: "k1", iv }, key);
+    const { record } = await encryptSnapshot(
+      plaintext,
+      { vv: vvUnsorted, keyId: "k1", iv },
+      key
+    );
     const parsed = parseEloRecordHeader(record);
     expect(parsed.kind).toBe(EloRecordKind.Snapshot);
     const hdr = parsed.header;
     if (hdr.kind === EloRecordKind.Snapshot) {
       // Expected lexicographic order: 0x01, 0x01ff, 0x02
-      const order = hdr.vv.map((e) => bytesToHex(e.peerId));
-      expect(order).toEqual([
-        "0x01",
-        "0x01ff",
-        "0x02",
-      ]);
+      const order = hdr.vv.map(e => bytesToHex(e.peerId));
+      expect(order).toEqual(["0x01", "0x01ff", "0x02"]);
     }
   });
 });

packages/loro-protocol/src/e2ee.test.ts packages/loro-protocol/tests/e2ee.test.tspackages/loro-protocol/src/e2ee.test.ts renamed to packages/loro-protocol/tests/e2ee.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { encode } from "./encoding";
+import { encode } from "../src/encoding";
 import {
   CrdtType,
   MessageType,
@@ -14,7 +14,7 @@ import {
   type DocUpdateFragment,
   type UpdateError,
   type Leave,
-} from "./protocol";
+} from "../src/protocol";
 
 // TODO: REVIEW ensure binary snapshots stay stable across changes to protocol
 
@@ -174,4 +174,3 @@ describe("encoding snapshots", () => {
     expect(bytesToHex(encode(msg))).toMatchSnapshot();
   });
 });
-

…/loro-protocol/src/encoding.snap.test.ts …oro-protocol/tests/encoding.snap.test.tspackages/loro-protocol/src/encoding.snap.test.ts renamed to packages/loro-protocol/tests/encoding.snap.test.ts packages/loro-protocol/src/encoding.snap.test.ts renamed to packages/loro-protocol/tests/encoding.snap.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { encode, decode, tryDecode } from "./encoding";
+import { encode, decode, tryDecode } from "../src/encoding";
 import {
   CrdtType,
   MessageType,
@@ -13,7 +13,7 @@ import {
   type DocUpdateFragment,
   type UpdateError,
   type Leave,
-} from "./protocol";
+} from "../src/protocol";
 
 describe("Message Encoding and Decoding", () => {
   const roomId = new Uint8Array([1, 2, 3, 4, 5]);
@@ -78,7 +78,8 @@ describe("Message Encoding and Decoding", () => {
 
       expect(decoded.type).toBe(MessageType.JoinResponseOk);
       expect(decoded.crdt).toBe(CrdtType.Yjs);
-      if (decoded.type !== MessageType.JoinResponseOk) throw new Error("bad type");
+      if (decoded.type !== MessageType.JoinResponseOk)
+        throw new Error("bad type");
       expect(decoded.permission).toBe("read");
       expect(Array.from(decoded.version)).toEqual([11, 22, 33]);
       expect(decoded.extra).toStrictEqual(new Uint8Array([]));
@@ -98,7 +99,8 @@ describe("Message Encoding and Decoding", () => {
       const decoded = decode(encoded);
 
       expect(decoded.type).toBe(MessageType.JoinResponseOk);
-      if (decoded.type !== MessageType.JoinResponseOk) throw new Error("bad type");
+      if (decoded.type !== MessageType.JoinResponseOk)
+        throw new Error("bad type");
       expect(decoded.permission).toBe("write");
       expect(Array.from(decoded.version)).toEqual([44, 55]);
       expect(decoded.extra).toBeDefined();
@@ -241,7 +243,8 @@ describe("Message Encoding and Decoding", () => {
       const decoded = decode(encoded);
 
       expect(decoded.type).toBe(MessageType.DocUpdateFragmentHeader);
-      if (decoded.type !== MessageType.DocUpdateFragmentHeader) throw new Error("bad type");
+      if (decoded.type !== MessageType.DocUpdateFragmentHeader)
+        throw new Error("bad type");
       expect(decoded.batchId).toBe("0xff11223344556677");
       expect(decoded.fragmentCount).toBe(10);
       expect(decoded.totalSizeBytes).toBe(1024000);
@@ -261,7 +264,8 @@ describe("Message Encoding and Decoding", () => {
       const decoded = decode(encoded);
 
       expect(decoded.type).toBe(MessageType.DocUpdateFragmentHeader);
-      if (decoded.type !== MessageType.DocUpdateFragmentHeader) throw new Error("bad type");
+      if (decoded.type !== MessageType.DocUpdateFragmentHeader)
+        throw new Error("bad type");
       expect(decoded.batchId).toBe("0x0000000000000000");
       expect(decoded.fragmentCount).toBe(1);
       expect(decoded.totalSizeBytes).toBe(100);
@@ -288,7 +292,8 @@ describe("Message Encoding and Decoding", () => {
       const decoded = decode(encoded);
 
       expect(decoded.type).toBe(MessageType.DocUpdateFragment);
-      if (decoded.type !== MessageType.DocUpdateFragment) throw new Error("bad type");
+      if (decoded.type !== MessageType.DocUpdateFragment)
+        throw new Error("bad type");
       expect(decoded.batchId).toBe("0x0000000000000000");
       expect(decoded.index).toBe(3);
       expect(Array.from(decoded.fragment)).toEqual(Array.from(fragmentData));
@@ -376,7 +381,8 @@ describe("Message Encoding and Decoding", () => {
         const encoded = encode(message);
         const decoded = decode(encoded);
         expect(decoded.type).toBe(MessageType.UpdateError);
-        if (decoded.type !== MessageType.UpdateError) throw new Error("bad type");
+        if (decoded.type !== MessageType.UpdateError)
+          throw new Error("bad type");
         expect(decoded.code).toBe(code);
         expect(decoded.message).toBe(`Error with code ${code}`);
       }