@peers-app/peers-sdk 0.19.13 → 0.20.0

package/dist/contracts/__tests__/builder.test.js

@@ -208,6 +208,30 @@ describe("definePackage", () => {
         expect(result.contracts[0].observables).toHaveLength(1);
         expect(result.contracts[0].observables[0].name).toBe("taskCount");
     });
+    it("emits contract events without sharing or mutating the caller's array", () => {
+        const eventContractId = (0, utils_1.newid)();
+        const events = [
+            {
+                name: "taskChanged",
+                description: "A task changed",
+                payloadFields: [{ name: "taskId", type: field_type_1.FieldType.id }],
+            },
+        ];
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const contract = pkg.contract(eventContractId, 1, "Event Contract");
+            contract.events = events;
+        });
+        const emittedEvents = result.contracts[0].events;
+        expect(emittedEvents).toEqual(events);
+        expect(emittedEvents).not.toBe(events);
+        emittedEvents?.push({
+            name: "otherEvent",
+            description: "Another event",
+            payloadFields: [],
+        });
+        expect(events).toHaveLength(1);
+    });
     it("uses provided name and description on the contract definition", () => {
         const cid = (0, utils_1.newid)();
         const result = (0, builder_1.definePackage)((pkg) => {

package/dist/contracts/__tests__/contract-events.test.d.ts

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

package/dist/contracts/__tests__/contract-events.test.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const events_1 = require("../../events");
+const field_type_1 = require("../../types/field-type");
+const utils_1 = require("../../utils");
+const contract_proxy_1 = require("../contract-proxy");
+const contract_transport_1 = require("../contract-transport");
+/** Contract-member name of the single event under test (distinct from the live bus name). */
+const EVENT_NAME = "widgetChanged";
+/** Flush pending micro/macrotasks so fire-and-forget subscribe requests land. */
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+/** A minimal contract that declares exactly one event. */
+function makeContract(contractId) {
+    return {
+        contractId,
+        version: 1,
+        devTag: "dev",
+        name: "Events Test Contract",
+        description: "For contract event proxy tests",
+        tables: [],
+        tools: [],
+        observables: [],
+        events: [
+            {
+                name: EVENT_NAME,
+                description: "Fires when a widget changes",
+                payloadFields: [{ name: "widgetId", type: field_type_1.FieldType.id, description: "ID" }],
+            },
+        ],
+    };
+}
+/**
+ * Wire a consumer to a provider session over an in-process transport pair. The live
+ * event uses a unique global bus name (via `newid()`) so subscriptions never collide
+ * across tests, while the contract-member name stays stable as {@link EVENT_NAME}.
+ */
+function wire(opts = {}) {
+    const contractId = (0, utils_1.newid)();
+    const emitter = new events_1.Emitter((0, utils_1.newid)());
+    const resolution = {
+        contractId,
+        version: 1,
+        events: { [EVENT_NAME]: emitter.event },
+    };
+    const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
+    const session = (0, contract_proxy_1.createContractProviderSession)(resolution, providerTransport, {
+        permissionCheck: opts.permissionCheck,
+        context: opts.context,
+    });
+    const consumer = (0, contract_proxy_1.createContractConsumer)(makeContract(contractId), consumerTransport);
+    return { consumer, session, emitter, contractId, consumerTransport, providerTransport };
+}
+describe("contract events — end-to-end", () => {
+    it("delivers a payload to a subscribed consumer", async () => {
+        const { consumer, session, emitter } = wire();
+        const received = [];
+        consumer.events[EVENT_NAME].subscribe((v) => received.push(v));
+        await flush();
+        await emitter.emit({ widgetId: "w1" });
+        expect(received).toEqual([{ widgetId: "w1" }]);
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract events — subscription gating", () => {
+    it("pushes nothing on the notify channel when nobody is subscribed", async () => {
+        const { emitter, providerTransport, session, consumer } = wire();
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        await emitter.emit({ widgetId: "w0" });
+        expect(notifySpy).not.toHaveBeenCalled();
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract events — unsubscribe + refcount", () => {
+    it("stops delivering after unsubscribe and detaches the live subscription", async () => {
+        const { consumer, session, emitter, providerTransport } = wire();
+        const originalSubscribe = emitter.event.subscribe;
+        const liveUnsubscribe = jest.fn();
+        jest.spyOn(emitter.event, "subscribe").mockImplementation((handler) => {
+            const subscription = originalSubscribe(handler);
+            return {
+                unsubscribe: () => {
+                    liveUnsubscribe();
+                    return subscription.unsubscribe();
+                },
+            };
+        });
+        const received = [];
+        const sub = consumer.events[EVENT_NAME].subscribe((v) => received.push(v));
+        await flush();
+        await emitter.emit({ widgetId: "a" });
+        expect(received).toEqual([{ widgetId: "a" }]);
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        sub.unsubscribe();
+        await flush();
+        // Refcount reached 0, so the provider detached its live handler: no further pushes.
+        expect(liveUnsubscribe).toHaveBeenCalledTimes(1);
+        await emitter.emit({ widgetId: "b" });
+        expect(notifySpy).not.toHaveBeenCalled();
+        expect(received).toEqual([{ widgetId: "a" }]);
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract events — fan-out", () => {
+    it("delivers to multiple subscribers through a single live subscription", async () => {
+        const { consumer, session, emitter, providerTransport } = wire();
+        const liveSubscribeSpy = jest.spyOn(emitter.event, "subscribe");
+        const a = [];
+        const b = [];
+        consumer.events[EVENT_NAME].subscribe((v) => a.push(v));
+        consumer.events[EVENT_NAME].subscribe((v) => b.push(v));
+        await flush();
+        // One live subscription is shared across both consumer subscriptions (refcount).
+        expect(liveSubscribeSpy).toHaveBeenCalledTimes(1);
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        await emitter.emit({ widgetId: "x" });
+        expect(a).toEqual([{ widgetId: "x" }]);
+        expect(b).toEqual([{ widgetId: "x" }]);
+        // One push per subscriptionId fanned out from the single emit.
+        expect(notifySpy).toHaveBeenCalledTimes(2);
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract events — missing provider member", () => {
+    it("reports a consumer subscribe failure when the resolution omits a declared event", async () => {
+        const consoleError = jest.spyOn(console, "error").mockImplementation();
+        const contractId = (0, utils_1.newid)();
+        const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
+        const session = (0, contract_proxy_1.createContractProviderSession)({ contractId, version: 1, events: {} }, providerTransport);
+        const consumer = (0, contract_proxy_1.createContractConsumer)(makeContract(contractId), consumerTransport);
+        const subscription = consumer.events[EVENT_NAME].subscribe(() => { });
+        await flush();
+        expect(subscription.unsubscribe()).toBe(false);
+        expect(consoleError).toHaveBeenCalledWith("Contract subscribe failed", expect.objectContaining({
+            message: expect.stringMatching(/does not provide event 'widgetChanged'/),
+        }));
+        consumer.dispose();
+        session.dispose();
+    });
+});
+describe("contract events — permission gating", () => {
+    it("rejects a denied subscribe and attaches no live subscription", async () => {
+        const localUserId = (0, utils_1.newid)();
+        const { consumerTransport, providerTransport, emitter, contractId, session, consumer } = wire({
+            permissionCheck: contract_proxy_1.sameUserContractPermissionCheck,
+            context: { localUserId, callerUserId: (0, utils_1.newid)() },
+        });
+        const call = {
+            contractId,
+            version: 1,
+            member: "event",
+            name: EVENT_NAME,
+            operation: "subscribe",
+            subscriptionId: (0, utils_1.newid)(),
+            args: [],
+        };
+        await expect(consumerTransport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, call)).rejects.toThrow(/Permission denied/);
+        // No live subscription attached, so emitting the event pushes nothing.
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        await emitter.emit({ widgetId: "z" });
+        expect(notifySpy).not.toHaveBeenCalled();
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract events — teardown", () => {
+    it("session.dispose() detaches live subscriptions and stops pushes", async () => {
+        const { consumer, session, emitter, providerTransport } = wire();
+        const received = [];
+        consumer.events[EVENT_NAME].subscribe((v) => received.push(v));
+        await flush();
+        await emitter.emit({ widgetId: "1" });
+        expect(received).toEqual([{ widgetId: "1" }]);
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        session.dispose();
+        await emitter.emit({ widgetId: "2" });
+        expect(notifySpy).not.toHaveBeenCalled();
+        expect(received).toEqual([{ widgetId: "1" }]);
+        consumer.dispose();
+    });
+    it("consumer.dispose() unsubscribes the provider and drops later pushes", async () => {
+        const { consumer, session, emitter, providerTransport } = wire();
+        const received = [];
+        consumer.events[EVENT_NAME].subscribe((v) => received.push(v));
+        await flush();
+        await emitter.emit({ widgetId: "1" });
+        expect(received).toEqual([{ widgetId: "1" }]);
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        consumer.dispose();
+        await flush();
+        await emitter.emit({ widgetId: "2" });
+        expect(notifySpy).not.toHaveBeenCalled();
+        expect(received).toEqual([{ widgetId: "1" }]);
+        session.dispose();
+    });
+});

package/dist/contracts/__tests__/contract-observables.test.d.ts

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

package/dist/contracts/__tests__/contract-observables.test.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const observable_1 = require("../../observable");
+const field_type_1 = require("../../types/field-type");
+const utils_1 = require("../../utils");
+const contract_proxy_1 = require("../contract-proxy");
+const contract_transport_1 = require("../contract-transport");
+/** Default contract-member name of the observable under test. */
+const OBS_NAME = "widgetCount";
+/** Flush pending micro/macrotasks so fire-and-forget subscribe/set requests land. */
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+function deferred() {
+    let resolve;
+    const promise = new Promise((resolvePromise) => {
+        resolve = resolvePromise;
+    });
+    return { promise, resolve };
+}
+afterEach(() => {
+    jest.restoreAllMocks();
+});
+/** A minimal contract declaring one observable per supplied name (no tables/tools/events). */
+function makeContract(contractId, names, writability) {
+    return {
+        contractId,
+        version: 1,
+        devTag: "dev",
+        name: "Observables Test Contract",
+        description: "For contract observable proxy tests",
+        tables: [],
+        tools: [],
+        observables: names.map((name) => ({
+            name,
+            description: `Observable ${name}`,
+            valueType: field_type_1.FieldType.number,
+            writable: writability[name],
+        })),
+        events: [],
+    };
+}
+/**
+ * Wire a consumer to a provider session over an in-process transport pair. Each entry in
+ * `values` becomes a live provider {@link Observable} seeded with that initial value; the
+ * returned `live` map exposes them so a test can drive provider-side changes and assert
+ * durability. The consumer subscribes to every observable implicitly at construction.
+ */
+function wire(opts = {}) {
+    const values = opts.values ?? { [OBS_NAME]: 0 };
+    const contractId = (0, utils_1.newid)();
+    const writability = Object.fromEntries(Object.keys(values).map((name) => [name, opts.writability?.[name] ?? true]));
+    const live = {};
+    for (const [name, value] of Object.entries(values)) {
+        live[name] = (0, observable_1.observable)(value);
+    }
+    const resolution = {
+        contractId,
+        version: 1,
+        observables: live,
+        observableWritability: writability,
+    };
+    const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
+    const session = (0, contract_proxy_1.createContractProviderSession)(resolution, providerTransport, {
+        permissionCheck: opts.permissionCheck,
+        context: opts.context,
+    });
+    const consumer = (0, contract_proxy_1.createContractConsumer)(makeContract(contractId, Object.keys(values), writability), consumerTransport);
+    return { consumer, session, live, contractId, consumerTransport, providerTransport };
+}
+describe("contract observables — initial snapshot", () => {
+    it("exposes the provider's initial value synchronously after loadingPromise resolves", async () => {
+        const { consumer, session } = wire({ values: { [OBS_NAME]: 42 } });
+        await consumer.loadingPromise;
+        expect(consumer.observables[OBS_NAME]()).toBe(42);
+        session.dispose();
+        consumer.dispose();
+    });
+    it("keeps a provider push that arrives before a stale initial get", async () => {
+        const contractId = (0, utils_1.newid)();
+        const live = (0, observable_1.observable)(0);
+        const staleGet = deferred();
+        const [baseConsumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
+        const consumerTransport = {
+            emit: (channel, ...args) => {
+                const call = args[0];
+                if (channel === contract_transport_1.CONTRACT_REQUEST_CHANNEL && call.operation === "get") {
+                    return staleGet.promise;
+                }
+                return baseConsumerTransport.emit(channel, ...args);
+            },
+            on: (channel, handler) => baseConsumerTransport.on(channel, handler),
+        };
+        const session = (0, contract_proxy_1.createContractProviderSession)({
+            contractId,
+            version: 1,
+            observables: { [OBS_NAME]: live },
+            observableWritability: { [OBS_NAME]: true },
+        }, providerTransport);
+        const consumer = (0, contract_proxy_1.createContractConsumer)(makeContract(contractId, [OBS_NAME], { [OBS_NAME]: true }), consumerTransport);
+        live(5);
+        staleGet.resolve(0);
+        await consumer.loadingPromise;
+        expect(consumer.observables[OBS_NAME]()).toBe(5);
+        consumer.dispose();
+        session.dispose();
+    });
+});
+describe("contract observables — always-on streaming", () => {
+    it("streams provider changes to the mirror with no explicit subscribe", async () => {
+        const { consumer, session, live } = wire({ values: { [OBS_NAME]: 0 } });
+        await consumer.loadingPromise;
+        // Provider-side change flows over the notify channel to the local mirror.
+        live[OBS_NAME](5);
+        await flush();
+        expect(consumer.observables[OBS_NAME]()).toBe(5);
+        live[OBS_NAME](6);
+        await flush();
+        expect(consumer.observables[OBS_NAME]()).toBe(6);
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract observables — writes", () => {
+    it("forwards a consumer write to the live observable (awaitable via loadingPromise)", async () => {
+        const { consumer, session, live } = wire({ values: { [OBS_NAME]: 0 } });
+        await consumer.loadingPromise;
+        // The mirror updates synchronously (optimistic) and a fire-and-forget `set` is sent.
+        consumer.observables[OBS_NAME](9);
+        expect(consumer.observables[OBS_NAME]()).toBe(9);
+        // Awaiting loadingPromise waits for the write to reach the live observable (durability).
+        await consumer.loadingPromise;
+        expect(live[OBS_NAME]()).toBe(9);
+        session.dispose();
+        consumer.dispose();
+    });
+    it("rejects read-only writes on both consumer and provider boundaries", async () => {
+        const { consumer, session, live, consumerTransport, contractId } = wire({
+            values: { [OBS_NAME]: 0 },
+            writability: { [OBS_NAME]: false },
+        });
+        await consumer.loadingPromise;
+        const emitSpy = jest.spyOn(consumerTransport, "emit");
+        expect(() => consumer.observables[OBS_NAME](9)).toThrow(/read-only/);
+        expect(consumer.observables[OBS_NAME]()).toBe(0);
+        expect(emitSpy).not.toHaveBeenCalled();
+        await expect(consumerTransport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, {
+            contractId,
+            version: 1,
+            member: "observable",
+            name: OBS_NAME,
+            operation: "set",
+            args: [9],
+        })).rejects.toThrow(/read-only/);
+        expect(live[OBS_NAME]()).toBe(0);
+        consumer.dispose();
+        session.dispose();
+    });
+    it("logs a failed writable set once and reconciles on the next provider push", async () => {
+        const consoleError = jest.spyOn(console, "error").mockImplementation();
+        const { consumer, session, live } = wire({
+            values: { [OBS_NAME]: 0 },
+            permissionCheck: (call) => call.operation !== "set",
+        });
+        await consumer.loadingPromise;
+        consumer.observables[OBS_NAME](9);
+        expect(consumer.observables[OBS_NAME]()).toBe(9);
+        await expect(consumer.loadingPromise).resolves.toBeUndefined();
+        expect(live[OBS_NAME]()).toBe(0);
+        expect(consoleError).toHaveBeenCalledTimes(1);
+        expect(consoleError).toHaveBeenCalledWith("Contract observable set failed", expect.objectContaining({ message: expect.stringMatching(/Permission denied/) }));
+        live[OBS_NAME](4);
+        await flush();
+        expect(consumer.observables[OBS_NAME]()).toBe(4);
+        consumer.dispose();
+        session.dispose();
+    });
+    it("serializes multiple writes through loadingPromise", async () => {
+        const gates = [deferred(), deferred()];
+        const starts = [deferred(), deferred()];
+        const seen = [];
+        let setIndex = 0;
+        const { consumer, session, live } = wire({
+            values: { [OBS_NAME]: 0 },
+            permissionCheck: (call) => {
+                if (call.operation !== "set") {
+                    return true;
+                }
+                const index = setIndex++;
+                seen.push(call.args[0]);
+                starts[index].resolve();
+                return gates[index].promise;
+            },
+        });
+        await consumer.loadingPromise;
+        consumer.observables[OBS_NAME](1);
+        consumer.observables[OBS_NAME](2);
+        await starts[0].promise;
+        expect(seen).toEqual([1]);
+        gates[0].resolve(true);
+        await starts[1].promise;
+        expect(seen).toEqual([1, 2]);
+        gates[1].resolve(true);
+        await consumer.loadingPromise;
+        expect(live[OBS_NAME]()).toBe(2);
+        expect(consumer.observables[OBS_NAME]()).toBe(2);
+        consumer.dispose();
+        session.dispose();
+    });
+});
+describe("contract observables — no echo loop", () => {
+    it("does not re-send a set when applying a provider push", async () => {
+        const { consumer, session, live, consumerTransport } = wire({ values: { [OBS_NAME]: 0 } });
+        await consumer.loadingPromise;
+        const emitSpy = jest.spyOn(consumerTransport, "emit");
+        live[OBS_NAME](3);
+        await flush();
+        expect(consumer.observables[OBS_NAME]()).toBe(3);
+        // Applying the push must not bounce a `set` back to the provider.
+        const setCalls = emitSpy.mock.calls.filter(([channel, call]) => channel === contract_transport_1.CONTRACT_REQUEST_CHANNEL && call.operation === "set");
+        expect(setCalls).toHaveLength(0);
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract observables — shared loadingPromise", () => {
+    it("resolves one proxy-level loadingPromise once every observable snapshot has loaded", async () => {
+        const { consumer, session } = wire({ values: { widgetCount: 1, gadgetCount: 2 } });
+        await consumer.loadingPromise;
+        expect(consumer.observables.widgetCount()).toBe(1);
+        expect(consumer.observables.gadgetCount()).toBe(2);
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract observables — permission gating", () => {
+    it("streams nothing when the implicit subscribe is permission-denied", async () => {
+        const consoleError = jest.spyOn(console, "error").mockImplementation();
+        const localUserId = (0, utils_1.newid)();
+        const { consumer, session, live, providerTransport } = wire({
+            values: { [OBS_NAME]: 0 },
+            permissionCheck: contract_proxy_1.sameUserContractPermissionCheck,
+            context: { localUserId, callerUserId: (0, utils_1.newid)() },
+        });
+        // Both the initial get and the implicit subscribe are denied; loadingPromise still
+        // resolves (failures are logged) and the mirror stays unset.
+        await consumer.loadingPromise;
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        live[OBS_NAME](5);
+        await flush();
+        expect(notifySpy).not.toHaveBeenCalled();
+        expect(consumer.observables[OBS_NAME]()).toBeUndefined();
+        expect(consoleError).toHaveBeenCalledTimes(2);
+        expect(consoleError).toHaveBeenCalledWith("Contract subscribe failed", expect.objectContaining({ message: expect.stringMatching(/Permission denied/) }));
+        expect(consoleError).toHaveBeenCalledWith("Contract observable initial get failed", expect.objectContaining({ message: expect.stringMatching(/Permission denied/) }));
+        session.dispose();
+        consumer.dispose();
+    });
+});
+describe("contract observables — teardown", () => {
+    it("session.dispose() detaches the live subscription and stops pushes", async () => {
+        const { consumer, session, live, providerTransport } = wire({ values: { [OBS_NAME]: 0 } });
+        await consumer.loadingPromise;
+        live[OBS_NAME](1);
+        await flush();
+        expect(consumer.observables[OBS_NAME]()).toBe(1);
+        const notifySpy = jest.spyOn(providerTransport, "emit");
+        session.dispose();
+        live[OBS_NAME](2);
+        await flush();
+        expect(notifySpy).not.toHaveBeenCalled();
+        expect(consumer.observables[OBS_NAME]()).toBe(1);
+        consumer.dispose();
+    });
+    it("consumer.dispose() unsubscribes the stream so the provider detaches", async () => {
+        const { consumer, session, live } = wire({ values: { [OBS_NAME]: 0 } });
+        await consumer.loadingPromise;
+        live[OBS_NAME](1);
+        await flush();
+        expect(consumer.observables[OBS_NAME]()).toBe(1);
+        // Exactly one live subscription (the refcounted session handler) is attached.
+        expect(live[OBS_NAME].subscriberCount()).toBe(1);
+        consumer.dispose();
+        await flush();
+        // The unsubscribe reached the provider and detached the last (only) subscriber.
+        expect(live[OBS_NAME].subscriberCount()).toBe(0);
+        live[OBS_NAME](2);
+        await flush();
+        expect(consumer.observables[OBS_NAME]()).toBe(1);
+        session.dispose();
+    });
+});

package/dist/contracts/__tests__/contract-provider-router.test.d.ts

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