@roomkit/state 1.0.0

package/README.md

@@ -0,0 +1,356 @@
+# @roomkit/state
+
+High-performance state synchronization library inspired by Colyseus Schema.
+
+## Features
+
+- 🎯 **Type-Safe**: Decorator-based schema definition with TypeScript support
+- ⚡ **High Performance**: Binary encoding with MessagePack, <1ms for 1000 entities
+- 📦 **Small Payloads**: 75-85% bandwidth reduction with compression
+- 🔄 **Automatic Tracking**: Automatic change detection for all data types
+- 🎮 **Game-Ready**: Tracked collections (Map, Array, Set) with automatic sync
+- 📊 **Delta Updates**: JSON Patch format for incremental state changes
+- 🧩 **Deep Nesting**: Automatic tracking of nested objects and collections
+- 🗜️ **Smart Compression**: Adaptive compression with entropy detection
+- 📦 **Batch Updates**: Queue system to reduce message frequency by 20x
+- 📈 **Performance Monitoring**: Built-in statistics and benchmarking
+
+## Installation
+
+```bash
+pnpm add @roomkit/state
+```
+
+## Performance Benchmarks
+
+| Scale | Players | Encoding Time | Data Size | Compression | Throughput |
+|-------|---------|---------------|-----------|-------------|------------|
+| Small | 10      | 0.087ms       | 474 bytes | 58.1% saved | 11,504/sec |
+| Medium| 100     | 0.210ms       | 3.3 KB    | 70.6% saved | 4,768/sec  |
+| Large | 1000    | 0.996ms       | 32 KB     | 72.5% saved | 1,004/sec  |
+
+**Delta Updates**: 0.006ms for 3 patches, 158,430 patches/sec
+**Batch Queue**: 20x message reduction, 4.25ms for 5000 patches
+**Change Tracking**: 0.010ms per cycle, 104,261 cycles/sec
+
+## Quick Start
+
+### Using Tracked Collections (Recommended)
+
+```typescript
+import { State, Field, MapField, TrackedMap } from '@roomkit/state';
+
+class Player {
+  @Field('string') name: string = '';
+  @Field('number') score: number = 0;
+}
+
+class GameState extends State {
+  @MapField(Player) players = new Map<string, Player>();
+  @Field('string') status: string = 'waiting';
+}
+
+// Usage
+const state = new GameState();
+state.startTracking(); // Automatically converts to TrackedMap
+
+// All modifications are automatically tracked
+state.players.set('p1', newPlayer);
+state.status = 'playing';
+
+// Get changes
+const patches = state.getPatches(); // JSON Patch format
+const encoded = state.encode(); // Binary MessagePack
+
+// Clear changes after sync
+state.clearChanges();
+```
+
+### Direct Tracked Collections Usage
+
+```typescript
+import { TrackedMap, TrackedArray, TrackedSet } from '@roomkit/state';
+
+// TrackedMap
+const players = new TrackedMap<string, Player>();
+players.startTracking();
+
+players.onChange((patches) => {
+  console.log('Players changed:', patches);
+});
+
+players.set('p1', new Player());
+// Triggers onChange with patches
+
+// TrackedArray
+const items = new TrackedArray<string>();
+items.startTracking();
+items.push('item1', 'item2');
+
+// TrackedSet
+const tags = new TrackedSet<string>();
+tags.startTracking();
+tags.add('tag1');
+```
+
+### Client-side State Synchronization
+
+```typescript
+import { StateDecoder } from '@roomkit/state/encoding';
+
+class ClientGameState {
+  players = new Map<string, any>();
+  scores: number[] = [];
+  status: string = 'waiting';
+  round: number = 0;
+}
+
+const decoder = new StateDecoder();
+const state = new ClientGameState();
+
+// Full state sync
+room.onMessage(MessageId.STATE_FULL, (message) => {
+  const decoded = decoder.decode(message.data);
+  Object.assign(state, decoded);
+});
+
+// Delta updates
+room.onMessage(MessageId.STATE_DELTA, (message) => {
+  decoder.applyPatches(state, message.patches);
+});
+```
+
+## API Reference
+
+### Decorators
+
+#### `@Field(type: FieldType)`
+Define a primitive field.
+
+```typescript
+@Field('string') name: string = '';
+@Field('number') health: number = 100;
+@Field('boolean') isAlive: boolean = true;
+```
+
+### TrackedMap
+
+```typescript
+@MapField(Player) players = new Map<string, Player>();
+```
+
+When `startTracking()` is called, automatically converts to `TrackedMap` which:
+- Tracks `set()`, `delete()`, `clear()` operations
+- Emits change events via `onChange(callback)`
+- Supports batch operations with `batch(fn)`
+
+### TrackedArray
+
+```typescript
+@ArrayField('number') scores: number[] = [];
+```
+
+Automatically converts to `TrackedArray` which tracks:
+- `push()`, `pop()`, `shift()`, `unshift()`
+- `splice()`, `sort()`, `reverse()`
+- Array element assignments
+
+### TrackedSet
+
+```typescript
+@SetField('string') tags = new Set<string>();
+```
+
+Automatically converts to `TrackedSet` which tracks:
+- `add()`, `delete()`, `clear()`
+- All modifications to the set
+
+### State Class
+
+#### `startTracking()`
+Start tracking changes to the state.
+
+#### `stopTracking()`
+Stop tracking changes.
+
+#### `getPatches(): Patch[]`
+Get accumulated changes as JSON Patch operations.
+
+#### `clearChanges()`
+Clear accumulated changes.
+
+#### `encode(full?: boolean, options?: EncodeOptions): EncodedState`
+Encode state to binary format.
+- `full=true`: Encode entire state
+- `full=false`: Encode only changes (delta)
+- Returns: `{ data, compressed, originalSize, compressedSize, compressionRatio }`
+
+#### `clone(): this`
+Create a deep copy of the state.
+
+### Compression Strategy
+
+```typescript
+import { CompressionStrategy, StateEncoder } from '@roomkit/state';
+
+// Create custom compression strategy
+const compressionStrategy = new CompressionStrategy({
+  threshold: 2048,           // Only compress data > 2KB
+  minCompressionRatio: 0.7,  // Skip if compression ratio > 70%
+  level: 9,                  // Compression level (1-9)
+  adaptive: true             // Learn from compression history
+});
+
+// Use with encoder
+const encoder = new StateEncoder(compressionStrategy);
+const encoded = encoder.encodeFull(state);
+
+// Get compression statistics
+const stats = encoder.getCompressionStats();
+console.log(`Compression rate: ${stats.compressionRate * 100}%`);
+console.log(`Average saving: ${stats.averageSaving} bytes`);
+```
+
+### Batch Update Queue
+
+```typescript
+import { BatchQueue } from '@roomkit/state';
+
+const queue = new BatchQueue({
+  maxWaitTime: 100,      // Flush every 100ms
+  maxPatchCount: 50,     // Or when 50 patches accumulated
+  maxBatchSize: 10240,   // Or when 10KB reached
+  enablePriority: true   // Enable priority queue
+});
+
+// Register flush callback
+queue.onFlush((updates) => {
+  const patches = updates.flatMap(u => u.patches);
+  const encoded = encoder.encodeDelta(patches);
+  sendToClients(encoded.data);
+});
+
+// Add updates to queue
+setInterval(() => {
+  const patches = state.getPatches();
+  if (patches.length > 0) {
+    queue.enqueue(patches, priority);
+    state.clearChanges();
+  }
+}, 16); // 60 FPS
+
+// Force flush on important events
+queue.forceFlush();
+
+// Get statistics
+const stats = queue.getStats();
+console.log(`Batching factor: ${stats.totalEnqueued / stats.totalBatches}x`);
+```
+
+### Complete Production Example
+
+```typescript
+import { 
+  State, Field, MapField,
+  StateEncoder, StateDecoder,
+  CompressionStrategy, BatchQueue
+} from '@roomkit/state';
+
+class GameState extends State {
+  @MapField(Player) players = new Map();
+  @Field('number') tick = 0;
+}
+
+// Server setup
+const state = new GameState();
+state.startTracking();
+
+const compressionStrategy = new CompressionStrategy({ adaptive: true });
+const encoder = new StateEncoder(compressionStrategy);
+const queue = new BatchQueue({ maxWaitTime: 50 });
+
+queue.onFlush((updates) => {
+  const patches = updates.flatMap(u => u.patches);
+  
+  // Optimize patches (merge, deduplicate)
+  const optimized = BatchQueue.optimizePatches(patches);
+  
+  // Encode with compression
+  const encoded = encoder.encodeDelta(optimized);
+  
+  // Send to clients
+  broadcast({
+    type: 'state_delta',
+    data: encoded.data,
+    compressed: encoded.compressed
+  });
+  
+  // Log stats
+  console.log(`Sent ${encoded.compressedSize} bytes (${optimized.length} patches)`);
+});
+
+// Game loop
+setInterval(() => {
+  // Update game logic
+  updateGame(state);
+  
+  // Queue changes
+  const patches = state.getPatches();
+  if (patches.length > 0) {
+    queue.enqueue(patches);
+    state.clearChanges();
+  }
+}, 16); // 60 FPS
+```
+
+## Performance Optimization Tips
+
+### 1. Choose Right Compression Threshold
+- **Small messages (< 1KB)**: Don't compress (overhead > benefit)
+- **Medium messages (1-10KB)**: Use level 3-6
+- **Large messages (> 10KB)**: Use level 6-9
+
+### 2. Batch Update Strategy
+- **Real-time games**: 50ms window, prioritize important events
+- **Turn-based games**: 200ms window, accumulate more changes
+- **MMO games**: 100ms window, use priority queue
+
+### 3. Memory Management
+- Call `resetStats()` periodically to avoid stat accumulation
+- Use `forceFlush()` at critical moments
+- Consider state sharding for large-scale applications
+
+## Benchmarking
+
+Run the built-in performance tests:
+
+```bash
+cd packages/state
+pnpm benchmark
+```
+
+This will test:
+- Full state encoding (with/without compression)
+- Delta encoding performance
+- Decoding performance
+- Change tracking overhead
+- Batch queue efficiency
+- Compression strategy effectiveness
+
+## Performance
+
+- **Full state encoding**: 0.087ms (10 players) → 0.996ms (1000 players)
+- **Delta encoding**: 0.006ms for 3 patches, 158,430 patches/sec
+- **Compression**: 58-73% size reduction for game states
+- **Batch queue**: 20x message frequency reduction
+- **Bandwidth reduction**: 75-85% vs JSON
+
+## Documentation
+
+- [Phase 1 Summary](./docs/PHASE1_SUMMARY.md) - Core state system
+- [Phase 2 Summary](./docs/PHASE2_SUMMARY.md) - Tracked collections
+- [Phase 3 Summary](./docs/PHASE3_SUMMARY.md) - Compression & optimization
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @roomkit/state - High-performance state synchronization library
+ *
+ * @example
+ * ```typescript
+ * import { State, Field, MapField } from '@roomkit/state';
+ *
+ * class Player {
+ *   @Field('string') name: string = '';
+ *   @Field('number') x: number = 0;
+ * }
+ *
+ * class GameState extends State {
+ *   @MapField(Player) players = new Map();
+ * }
+ *
+ * const state = new GameState();
+ * state.startTracking();
+ *
+ * // Changes are automatically tracked
+ * state.players.set('p1', new Player());
+ *
+ * // Get patches
+ * const patches = state.getPatches();
+ *
+ * // Encode to binary
+ * const encoded = state.encode(true); // full state
+ * const delta = state.encode(false);   // only changes
+ * ```
+ */
+export * from './State.js';
+export * from './types.js';
+export * from './decorators/index.js';
+export * from './tracking/ChangeTracker.js';
+export * from './encoding/index.js';
+export * from './collections/index.js';
+export * from './compression/index.js';
+export * from './optimization/index.js';
+export type { Patch, FieldType, FieldMetadata, EncodedState, EncodeOptions, DecodeOptions, TrackingOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AAGxC,YAAY,EACV,KAAK,EACL,SAAS,EACT,aAAa,EACb,YAAY,EACZ,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * @roomkit/state - High-performance state synchronization library
+ *
+ * @example
+ * ```typescript
+ * import { State, Field, MapField } from '@roomkit/state';
+ *
+ * class Player {
+ *   @Field('string') name: string = '';
+ *   @Field('number') x: number = 0;
+ * }
+ *
+ * class GameState extends State {
+ *   @MapField(Player) players = new Map();
+ * }
+ *
+ * const state = new GameState();
+ * state.startTracking();
+ *
+ * // Changes are automatically tracked
+ * state.players.set('p1', new Player());
+ *
+ * // Get patches
+ * const patches = state.getPatches();
+ *
+ * // Encode to binary
+ * const encoded = state.encode(true); // full state
+ * const delta = state.encode(false);   // only changes
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./State.js"), exports);
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./decorators/index.js"), exports);
+__exportStar(require("./tracking/ChangeTracker.js"), exports);
+__exportStar(require("./encoding/index.js"), exports);
+__exportStar(require("./collections/index.js"), exports);
+__exportStar(require("./compression/index.js"), exports);
+__exportStar(require("./optimization/index.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,6CAA2B;AAC3B,wDAAsC;AACtC,8DAA4C;AAC5C,sDAAoC;AACpC,yDAAuC;AACvC,yDAAuC;AACvC,0DAAwC"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@roomkit/state",
+  "version": "1.0.0",
+  "description": "High-performance state synchronization library inspired by Colyseus Schema",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./decorators": {
+      "types": "./dist/decorators/index.d.ts",
+      "import": "./dist/decorators/index.js"
+    },
+    "./collections": {
+      "types": "./dist/collections/index.d.ts",
+      "import": "./dist/collections/index.js"
+    },
+    "./encoding": {
+      "types": "./dist/encoding/index.d.ts",
+      "import": "./dist/encoding/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:examples": "tsc --project tsconfig.examples.json",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist dist-examples",
+    "benchmark": "pnpm build:examples && node dist-examples/benchmarks/performance.js",
+    "test": "jest"
+  },
+  "keywords": [
+    "state",
+    "synchronization",
+    "schema",
+    "binary",
+    "msgpack",
+    "realtime",
+    "game"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/daxing/gateway-worker.git",
+    "directory": "packages/state"
+  },
+  "bugs": {
+    "url": "https://github.com/daxing/gateway-worker/issues"
+  },
+  "homepage": "https://github.com/daxing/gateway-worker#readme",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.0.0-beta2",
+    "fast-json-patch": "^3.1.1",
+    "pako": "^2.1.0",
+    "reflect-metadata": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/pako": "^2.0.3",
+    "typescript": "^5.3.3"
+  }
+}