wenay-common2 1.0.68 → 1.0.70

package/lib/Common/peer/peer-relay.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPatchRelayJournal = createPatchRelayJournal;
+const Listen_1 = require("../events/Listen");
+const store_1 = require("../Observe/store");
+const store_replay_1 = require("../Observe/store-replay");
+function condensePatchTail(tail) {
+    const held = new Map();
+    for (const ev of tail) {
+        const k = (0, store_replay_1.storePatchKey)(ev.event[0]);
+        if (k == null)
+            return tail;
+        held.delete(k);
+        held.set(k, ev);
+    }
+    return Array.from(held.values());
+}
+function createPatchRelayJournal(opts = {}) {
+    const { history = 1024 } = opts;
+    const [emitLine, line] = (0, Listen_1.listen)();
+    const fold = (0, store_1.createStore)({}, { drain: 'micro' });
+    let ring = [];
+    let last = -1;
+    let lastTs = 0;
+    let hasState = false;
+    function push(env) {
+        if (env == null || typeof env.seq != 'number')
+            return false;
+        const patch = env.event?.[0];
+        if (patch == null || !Array.isArray(patch.path))
+            return false;
+        const isRoot = patch.path.length == 0;
+        if (env.seq <= last) {
+            if (!isRoot || env.seq == last)
+                return false;
+            ring = [];
+        }
+        last = env.seq;
+        lastTs = env.ts ?? lastTs;
+        hasState = true;
+        (0, store_1.applyStorePatch)(fold, patch);
+        ring.push(env);
+        if (ring.length > history)
+            ring.splice(0, ring.length - history);
+        emitLine(env);
+        return true;
+    }
+    function keyframe() {
+        if (!hasState)
+            return null;
+        return { seq: last, ts: lastTs, event: [{ path: [], exists: true, value: fold.snapshot() }] };
+    }
+    function since(seq) {
+        if (!hasState)
+            return null;
+        if (seq >= last)
+            return [];
+        if (!ring.length || seq < ring[0].seq - 1)
+            return null;
+        return ring.filter(ev => ev.seq > seq);
+    }
+    function frame(seq, _hint) {
+        const tail = since(seq);
+        if (tail)
+            return condensePatchTail(tail);
+        const kf = keyframe();
+        return kf ? [kf] : null;
+    }
+    const remote = { line, since, keyframe, frame };
+    return {
+        push,
+        remote,
+        seq: () => last,
+        snapshot: () => fold.snapshot(),
+        close: () => { line.close(); },
+    };
+}

package/lib/index.d.ts

@@ -35,3 +35,4 @@ export * as Color from "./Common/Color";
 export * as Observe from "./Common/Observe";
 export * as Replay from "./Common/events/replay-index";
 export * as Media from "./Common/media/media-index";
+export * as Peer from "./Common/peer/peer-index";

package/lib/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Media = exports.Replay = exports.Observe = exports.Color = exports.Time = exports.Params = exports.Bars = exports.Math = void 0;
+exports.Peer = exports.Media = exports.Replay = exports.Observe = exports.Color = exports.Time = exports.Params = exports.Bars = exports.Math = void 0;
 __exportStar(require("./Common/node_console"), exports);
 __exportStar(require("./Common/core/Decorator"), exports);
 __exportStar(require("./Common/core/BaseTypes"), exports);
@@ -74,3 +74,4 @@ exports.Color = __importStar(require("./Common/Color"));
 exports.Observe = __importStar(require("./Common/Observe"));
 exports.Replay = __importStar(require("./Common/events/replay-index"));
 exports.Media = __importStar(require("./Common/media/media-index"));
+exports.Peer = __importStar(require("./Common/peer/peer-index"));

package/observe/PLAN.md

@@ -0,0 +1,131 @@
+# observe — status and contract
+
+`observe` is the small reactive core for coarse, consistent invalidation.
+It is intentionally not a MobX/Vue clone: the API does not expose deltas,
+paths, old values, or computed values.
+
+Implemented surface:
+
+```ts
+import {reactive, onUpdate, flushReactive, listenUpdate} from './reactive'
+
+const state = reactive({
+    price: 100,
+    balances: {BTC: 1, ETH: 10},
+})
+
+const off = onUpdate(state.balances, () => {
+    const total = Object.values(state.balances).reduce((a, b) => a + b, 0)
+})
+
+state.balances.BTC = 2
+state.balances = {SOL: 250, DOT: 150, ADA: 100}
+await flushReactive(state.balances)
+off()
+```
+
+## Core idea
+
+Subscribe to the fact that something under a node changed. The callback receives
+no `(key, value)`, no diff, and no string path. It fires after the settled batch;
+the consumer re-reads the current state through normal typed property access.
+
+This is the intended trading/backend use case:
+
+- a feed applies several synchronous mutations;
+- subscribers fire once after the batch;
+- aggregate code reads a consistent snapshot;
+- replacing a whole subtree does not break existing subscribers on that subtree.
+
+## What is implemented
+
+- `reactive(obj, opts?)` wraps a plain object/array tree in stable proxies.
+- `onUpdate(node, cb)` subscribes to a reactive node and returns an idempotent `off()`.
+- `flushReactive(node)` resolves after queued drains for that reactive tree settle.
+- `listenUpdate(node)` adapts a node to the project's existing `Listen` shape for RPC.
+- Synchronous bursts are coalesced into one callback per subscribed node.
+- A callback that mutates state queues a follow-up drain instead of recursing.
+- A throwing callback does not stop sibling subscribers; the first error is re-thrown asynchronously.
+- Whole-subtree replacement preserves existing child proxy identity where possible.
+- `depth` makes deeper objects opaque leaves.
+- `eager` pre-walks/wraps the tree to `depth`.
+- `drain` is pluggable: `'immediate'`, `'micro'`, `number`, or custom scheduler.
+- Plain objects and arrays are reactive. `Date`, `Map`, `Set`, and class instances are opaque leaves.
+
+## Chosen laziness model
+
+The original design considered subscription-driven wrapping with `subtreeSubs`.
+The implemented model is simpler and is now the contract:
+
+- root is always a proxy;
+- child proxies are created lazily on read, up to `depth`;
+- with zero subscribers, writes only mutate and do not schedule drains;
+- built-in/class objects are not proxied.
+
+So this is **lazy-on-read**, not subscription-driven wrapping. That is a conscious
+tradeoff: it keeps normal `onUpdate(state.a.b, cb)` usage simple and avoids the
+identity caveat of fully lazy upgrades.
+
+## Options
+
+```ts
+type Drain =
+    | 'micro'
+    | 'immediate'
+    | number
+    | ((flush: () => void) => void)
+
+type Opts = {
+    drain?: Drain      // default: 'immediate'
+    depth?: number     // default: Infinity
+    eager?: boolean    // default: false
+}
+```
+
+Drain semantics:
+
+- `'immediate'`: uses `setImmediate` when available, otherwise `setTimeout(0)`.
+- `'micro'`: uses `queueMicrotask`.
+- `number`: uses `setTimeout(ms)` and coalesces to the last state.
+- custom scheduler: receives the flush function.
+
+Use `flushReactive(node)` in tests/examples instead of guessing event-loop order.
+
+## Verified by oracle
+
+Run:
+
+```bash
+npx tsx observe/reactive.test.ts
+npx tsx observe/usage.ts
+```
+
+The oracle covers:
+
+- plain and nested read/write;
+- cold writes with no subscribers;
+- one fact per batch;
+- the `$500` whole-map replacement case;
+- subscriber survival across middle-node replacement;
+- root subscriber behavior;
+- unsubscribe before flush;
+- mutation from inside callback;
+- arrays;
+- opaque `Date`/`Map`/class leaves;
+- `depth` behavior;
+- callback error isolation.
+
+## Not implemented here
+
+These are intentionally not part of the finished local core:
+
+- per-key delta streams;
+- string paths;
+- `computed`/derived graph primitives;
+- dependency tracking by reads;
+- automatic network mirror over RPC.
+
+`listenUpdate(node)` already stacks with `createRpcServerAuto` as a notification
+stream. The larger mirror extension remains separate: subscribe to a subtree,
+send whole snapshots on settle/throttle, and atomically replace the mirror branch
+on the client.

package/observe/README.md

@@ -0,0 +1,226 @@
+# observe
+
+Minimal reactive object core for coarse, consistent invalidation.
+
+The idea is simple: subscribe to the fact that a reactive subtree changed, then
+re-read the current state. There are no deltas, no string paths, no old/new
+values, and no computed graph in the core.
+
+## API
+
+```ts
+import {reactive, onUpdate, flushReactive, listenUpdate} from './reactive'
+```
+
+### `reactive(obj, opts?)`
+
+Wraps a plain object/array tree.
+
+```ts
+const state = reactive({
+    balances: {BTC: 100, ETH: 400},
+    price: 0,
+})
+```
+
+You read and write normally:
+
+```ts
+state.price = 101
+state.balances.BTC = 120
+state.balances = {SOL: 250, DOT: 150, ADA: 100}
+```
+
+### `onUpdate(node, cb)`
+
+Subscribes to a node. The callback receives no arguments. It means only:
+
+> Something under this node changed; the batch is settled; read the state now.
+
+```ts
+const off = onUpdate(state.balances, () => {
+    const total = Object.values(state.balances).reduce((a, b) => a + b, 0)
+    console.log(total)
+})
+
+off()
+```
+
+### `flushReactive(node)`
+
+Returns a promise that resolves after queued updates for this reactive tree
+settle. Use it in tests, demos, and scripts instead of guessing event-loop order.
+
+```ts
+state.balances.BTC = 200
+await flushReactive(state.balances)
+```
+
+### `listenUpdate(node)`
+
+Adapts an Observe node to the project's existing `Listen` shape. This is the
+bridge for RPC: `createRpcServerAuto` already knows how to expose `Listen`
+objects as remote subscriptions.
+
+```ts
+const facade = {
+    getBalances: () => state.balances,
+    balancesChanged: listenUpdate(state.balances),
+}
+```
+
+## Full Example
+
+```ts
+import {reactive, onUpdate, flushReactive} from './reactive'
+
+const sum = (o: Record<string, number>) =>
+    Object.values(o).reduce((a, b) => a + b, 0)
+
+async function main() {
+    const account = reactive({
+        balances: {BTC: 100, ETH: 400},
+        positions: {
+            BTC: {qty: 0.5},
+        },
+    })
+
+    let balanceRecalc = 0
+    let positionSync = 0
+
+    const offBalances = onUpdate(account.balances, () => {
+        balanceRecalc++
+        console.log('balances total:', sum(account.balances))
+    })
+
+    const offPositions = onUpdate(account.positions, () => {
+        positionSync++
+        console.log('positions changed:', Object.keys(account.positions))
+    })
+
+    // Several synchronous mutations become one callback.
+    account.balances.BTC = 120
+    account.balances.ETH = 380
+    account.balances.SOL = 0
+    await flushReactive(account.balances)
+
+    console.log('balance recalculations:', balanceRecalc) // 1
+
+    // Whole-subtree replacement is the important case:
+    // the old account.balances proxy keeps working as a subscription target.
+    account.balances = {SOL: 250, DOT: 150, ADA: 100}
+    await flushReactive(account.balances)
+
+    console.log('new total:', sum(account.balances))       // 500
+    console.log('balance recalculations:', balanceRecalc) // 2
+
+    // Deep writes under an already-read branch are reactive.
+    account.positions.BTC.qty = 0.7
+    account.positions.ETH = {qty: 3}
+    await flushReactive(account.positions)
+
+    console.log('position syncs:', positionSync) // 1
+
+    offBalances()
+    offPositions()
+}
+
+main()
+```
+
+## Options
+
+```ts
+type Opts = {
+    drain?: 'immediate' | 'micro' | number | ((flush: () => void) => void)
+    depth?: number
+    eager?: boolean
+}
+```
+
+Defaults:
+
+```ts
+reactive(obj, {
+    drain: 'immediate',
+    depth: Infinity,
+    eager: false,
+})
+```
+
+Drain modes:
+
+- `'immediate'`: `setImmediate` when available, otherwise `setTimeout(0)`.
+- `'micro'`: `queueMicrotask`.
+- `number`: `setTimeout(number)`, useful as a throttle.
+- custom function: bring your own scheduler.
+
+Example throttle:
+
+```ts
+const md = reactive({price: 0}, {drain: 50})
+let heavyRecalc = 0
+
+onUpdate(md, () => {
+    heavyRecalc++
+})
+
+for (let i = 0; i < 1000; i++) md.price = i
+await flushReactive(md)
+
+console.log(heavyRecalc) // 1
+```
+
+## Current Contract
+
+- Root is always a proxy.
+- Child proxies are created lazily on read.
+- With zero subscribers, writes do not schedule drains.
+- Plain objects and arrays are reactive.
+- `Date`, `Map`, `Set`, and class instances are opaque leaves.
+- Callback errors do not stop sibling subscribers; the first error is re-thrown asynchronously.
+- A callback that mutates state queues a follow-up drain instead of recursing.
+
+## What Was Finished
+
+- Local in-process core: `reactive`, `onUpdate`, `flushReactive`.
+- RPC bridge: `listenUpdate(node)` returns a `Listen` object.
+- Coalesced settled updates.
+- Whole-subtree replacement.
+- Depth/eager/drain options.
+- Edge-case oracle in `reactive.test.ts`.
+- Usage scenarios in `usage.ts`.
+
+## What Is Not Part Of This Core
+
+- Per-key delta streams.
+- String-path subscriptions.
+- `computed` or dependency tracking.
+- Automatic RPC snapshot/mirror layer.
+
+Those live in the layers built ON TOP of this core, not inside it.
+
+## Where This Went
+
+The sandbox has been assembled: the canonical core is
+`src/Common/Observe/reactive.ts`, exported from the package as `Observe`.
+Layers on top of it (documented in `wenay-common2.md` / `wenay-common2-rare.md`):
+
+- **Store** — `createStore` wraps the core with typed path nodes (`state` / `node` /
+  `update(mask)`), `src/Common/Observe/store.ts`.
+- **Mirror sync** — `exposeStore` ⇄ `createStoreMirror`: snapshots + changed
+  notifications over RPC, optional push channels (`patches` / `changedData`).
+- **Sequenced replay line** — the store's patch stream numbered by seq: keyframe
+  catch-up, reconnect by seq, per-client conflation, archived history with
+  time-travel. Exported as `Replay` (generic line) and via `Observe`
+  (`exposeStoreReplay` / `syncStoreReplay` / `storeReplayAt`); oracles in `replay/`,
+  status in `replay/PLAN.md`.
+
+## Run
+
+```bash
+npx tsx observe/reactive.test.ts
+npx tsx observe/store.test.ts
+npx tsx observe/usage.ts
+npx tsx observe/usage-real-socket.ts
+```

package/observe/hot-write.test.ts

@@ -0,0 +1,95 @@
+// ============================================================
+//  observe/hot-write.test.ts
+//
+//  Hot-write масштабирование reactive: тикающая карта котировок
+//  (state[symbol] = quote, тысячи разных ключей за drain-окно) при
+//  подключённом changedPaths-потребителе (pathLive > 0).
+//  Оракул: дедуп dirty-путей keyed-структурой (не линейным сканом) →
+//  окно из 4x ключей стоит ~4x времени, НЕ ~16x. Плюс корректность:
+//  дедуп в окне, symbol-идентичность ключей, отсутствие склейки
+//  строковых сегментов.
+//  Запуск:
+//      npx ts-node observe/hot-write.test.ts
+// ============================================================
+
+import {reactive, onUpdatePaths, flushReactive} from '../src/Common/Observe/reactive'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+
+async function benchWindow(n: number, rounds: number) {
+    const state = reactive<any>({quotes: {}}, {drain: 'micro'})
+    for (let i = 0; i < n; i++) state.quotes['s' + i] = 0    // ключи заранее: меряем чистые записи
+    const off = onUpdatePaths(state, () => {})
+    await flushReactive(state)
+    let best = Infinity
+    for (let r = 1; r <= rounds; r++) {
+        const t0 = process.hrtime.bigint()
+        for (let i = 0; i < n; i++) state.quotes['s' + i] = r * n + i
+        await flushReactive(state)
+        best = Math.min(best, Number(process.hrtime.bigint() - t0) / 1e6)
+    }
+    off()
+    return best
+}
+
+async function main() {
+    console.log('\n[hot-write] changedPaths correctness under a hot window')
+    {
+        const state = reactive<any>({quotes: {}}, {drain: 'micro'})
+        const windows: PropertyKey[][][] = []
+        const off = onUpdatePaths(state, ch => windows.push(ch.paths))
+        for (let i = 0; i < 5; i++) state.quotes['s' + i] = i
+        for (let i = 0; i < 5; i++) state.quotes['s' + i] = i + 100   // повторное касание тех же ключей
+        await flushReactive(state)
+        ok(windows.length == 1, 'one settled batch')
+        ok(windows[0].length == 5, `same key touched twice dedups to one path (got ${windows[0].length})`)
+        ok(windows[0].every(p => p.length == 2 && p[0] == 'quotes'), 'paths are root-relative [quotes, key]')
+        off()
+    }
+
+    console.log('\n[hot-write] symbol keys stay identity-safe in the dedup')
+    {
+        const s1 = Symbol('k'), s2 = Symbol('k')                      // одинаковое описание, разная идентичность
+        const state = reactive<any>({}, {drain: 'micro'})
+        const windows: PropertyKey[][][] = []
+        const off = onUpdatePaths(state, ch => windows.push(ch.paths))
+        state[s1] = 1
+        state[s2] = 2
+        state[s1] = 3                                                 // повтор первого символа
+        await flushReactive(state)
+        ok(windows[0].length == 2, `two same-description symbols = two paths, repeat dedups (got ${windows[0].length})`)
+        off()
+    }
+
+    console.log('\n[hot-write] string segments cannot glue across boundaries')
+    {
+        const state = reactive<any>({'a': {'b|c': 0}, 'a|b': {'c': 0}}, {drain: 'micro'})
+        const windows: PropertyKey[][][] = []
+        const off = onUpdatePaths(state, ch => windows.push(ch.paths))
+        state['a']['b|c'] = 1
+        state['a|b']['c'] = 2
+        await flushReactive(state)
+        ok(windows[0].length == 2, `[a][b|c] and [a|b][c] are distinct paths (got ${windows[0].length})`)
+        off()
+    }
+
+    console.log('\n[hot-write] near-linear scaling with a changedPaths subscriber')
+    {
+        await benchWindow(200, 2)                                     // прогрев (JIT)
+        const n = 500, m = 2000, rounds = 5
+        const tN = await benchWindow(n, rounds)
+        const tM = await benchWindow(m, rounds)
+        const ratio = tM / tN
+        console.log(`  [bench] ${n} keys/window: ${tN.toFixed(2)}ms · ${m} keys/window: ${tM.toFixed(2)}ms · ratio ${ratio.toFixed(1)}x`)
+        ok(ratio < 10, `4x keys cost ~4x, not ~16x (ratio ${ratio.toFixed(1)}x < 10x)`)
+    }
+
+    console.log(fails ? `\n${fails} FAILED` : '\nall passed')
+    if (fails) process.exit(1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/observe/listen-core.test.ts

@@ -0,0 +1,66 @@
+import {createListen, createListenCore, listenStore} from '../src/Common/events/Listen'
+
+let fails = 0
+const ok = (c: any, m: string) => { if (!c) { fails++; console.log('  FAIL', m) } else console.log('  OK  ', m) }
+
+async function main() {
+    console.log('\n[slim-listen] core on/off/once')
+    {
+        const listen = createListenCore<[number]>()
+        const seen: number[] = []
+        const off = listen.on(v => seen.push(v))
+        listen.emit(1)
+        off()
+        listen.emit(2)
+        listen.once(v => seen.push(v * 10))
+        listen.emit(3)
+        listen.emit(4)
+        ok(JSON.stringify(seen) == '[1,30]', 'core delivers on, removes by off, and once fires once')
+        ok(listen.count() == 0, 'core once removes itself')
+    }
+
+    console.log('\n[slim-listen] core key replacement')
+    {
+        const listen = createListenCore<[number]>()
+        const seen: string[] = []
+        listen.on(v => seen.push('a' + v), {key: 'slot'})
+        listen.on(v => seen.push('b' + v), {key: 'slot'})
+        listen.emit(5)
+        ok(JSON.stringify(seen) == '["b5"]', 'same key replaces previous callback')
+        ok(listen.count() == 1, 'key replacement keeps one live subscriber')
+    }
+
+    console.log('\n[slim-listen] full lifecycle and close hooks')
+    {
+        let producerClosed = 0
+        let cbClosed = 0
+        let streamClosed = 0
+        const listen = createListen<[number]>(() => () => { producerClosed++ })
+        listen.run()
+        const off = listen.on(() => {}, {cbClose: () => { cbClosed++ }})
+        off()
+        listen.on(() => {}, {cbClose: () => { cbClosed++ }})
+        listen.onClose(() => { streamClosed++ })
+        listen.close()
+        ok(cbClosed == 1, 'cbClose fires on full close for live subscribers only')
+        ok(producerClosed == 1, 'producer cleanup fires on close')
+        ok(streamClosed == 1, 'onClose fires on close')
+        ok(listen.count() == 0, 'full close clears listeners')
+    }
+
+    console.log('\n[slim-listen] store once(current) waits when current is absent')
+    {
+        const [emit, listen] = listenStore<[number]>({current: () => undefined})
+        const seen: number[] = []
+        listen.once(v => seen.push(v), {current: true})
+        emit(8)
+        emit(9)
+        ok(JSON.stringify(seen) == '[8]', 'once(current) falls back to one future event when store has no value')
+    }
+
+    console.log(`\n${fails == 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails == 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })
+

package/observe/listen-store.test.ts

@@ -0,0 +1,56 @@
+import {listen as createListenPair, listenStore} from '../src/Common/events/Listen'
+
+let fails = 0
+const ok = (c: any, m: string) => { if (!c) { fails++; console.log('  FAIL', m) } else console.log('  OK  ', m) }
+
+async function main() {
+    console.log('\n[listen-store] base listen is a pure event list')
+    {
+        const [emit, listen] = createListenPair<[number]>()
+        emit(1)
+        let got = 0
+        ;(listen.on as any)((v: number) => { got = v }, {current: true})
+        ok(got == 0, 'base listen ignores current and stores no value')
+    }
+
+    console.log('\n[listen-store] listenStore reads external store reference')
+    {
+        const box = {value: 1}
+        const [emit, listen] = listenStore<[number]>({current: () => [box.value]})
+        emit(99)
+        let got = 0
+        listen.on(v => { got = v }, {current: true})
+        ok(got == 1, 'current:true reads store provider, not emitted args')
+        box.value = 9
+        got = 0
+        listen.once(v => { got = v }, {current: true})
+        ok(got == 9, 'once(current) reads changed external value')
+    }
+
+    console.log('\n[listen-store] per-subscription getter overrides wrapper provider')
+    {
+        const box = {value: 1}
+        const [emit, listen] = listenStore<[number]>({current: () => [box.value]})
+        emit(7)
+        let got = 0
+        listen.on(v => { got = v }, {current: () => [42]})
+        ok(got == 42, 'per-call current getter is used for that subscriber')
+    }
+
+    console.log('\n[listen-store] normal events still flow through the wrapper')
+    {
+        const box = {value: 1}
+        const [emit, listen] = listenStore<[number]>({current: () => [box.value]})
+        const seen: number[] = []
+        const off = listen.on(v => seen.push(v))
+        emit(5)
+        off()
+        emit(6)
+        ok(JSON.stringify(seen) == '[5]', 'wrapper delegates event delivery and off() to base listen')
+    }
+
+    console.log(`\n${fails == 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails == 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })