@c9up/ream 0.1.3

package/dist/events/testing/FakeBus.js

@@ -0,0 +1,356 @@
+/**
+ * In-memory `EventBus` substitute for tests — captures every
+ * `emit(name, data)` / `request(name, data)` call and exposes
+ * `assertEmitted` / `assertNotEmitted` helpers in the same shape as
+ * Rover's `FakeMail`, Bay's `FakeQueue`, Storage's `FakeStorage`,
+ * Nova's `FakeNova`, and Relay's `FakeRelay`.
+ *
+ * Mirrors the public `EventBus` surface (`emit`, `subscribe`,
+ * `unsubscribe`, `onRequest`, `request`, `matchesWildcard`,
+ * `subscriptionCount`) with pure-TS, NAPI-free semantics. Wildcard
+ * matching is ported from `crates/ream-events/src/router.rs` — the
+ * Rust router is authoritative; any divergence is a bug here.
+ *
+ * Reach via `@c9up/ream/events/testing` (NOT the main barrel).
+ */
+export class FakeBus {
+    #emitted = [];
+    #requests = [];
+    #subscribers = new Map();
+    #requestHandlers = new Map();
+    #nextSubId = 1;
+    emit(name, data) {
+        const { parsedData, correlationId, causationId } = parseEmitData(data);
+        const entry = {
+            kind: 'emit',
+            name,
+            data,
+            parsedData,
+            correlationId,
+            causationId,
+        };
+        this.#emitted.push(entry);
+        // Snapshot subscribers so a callback adding/removing during dispatch
+        // can't perturb the in-flight iteration — matches the router.rs
+        // "clone matching handlers; release lock; call without holding lock"
+        // pattern.
+        const targets = [];
+        for (const sub of this.#subscribers.values()) {
+            if (this.matchesWildcard(sub.pattern, name))
+                targets.push(sub);
+        }
+        const payloadJson = buildEventJson(entry);
+        for (const sub of targets) {
+            // Subscribers can be sync (`(json) => void`) or async (`(json) =>
+            // Promise<void>`). Sync throws surface via the `try/catch`; async
+            // rejections would otherwise escape to `unhandledRejection`. Wrap
+            // both paths so a misbehaving subscriber logs loudly instead of
+            // crashing the test process — mirror of the request-handler error
+            // surface at `onError` below.
+            try {
+                const ret = sub.callback(payloadJson);
+                if (isThenable(ret)) {
+                    ret.then(undefined, (err) => {
+                        console.error(`[FakeBus] subscriber for "${sub.pattern}" rejected on event "${name}":`, err);
+                    });
+                }
+            }
+            catch (err) {
+                console.error(`[FakeBus] subscriber for "${sub.pattern}" threw on event "${name}":`, err);
+            }
+        }
+        return Promise.resolve('ok');
+    }
+    subscribe(pattern, callback) {
+        const id = this.#nextSubId++;
+        this.#subscribers.set(id, { pattern, callback });
+        return id;
+    }
+    unsubscribe(subscriptionId) {
+        this.#subscribers.delete(subscriptionId);
+        return Promise.resolve();
+    }
+    onRequest(name, callback) {
+        if (this.#requestHandlers.has(name)) {
+            throw new Error(`FakeBus.onRequest: a handler is already registered for "${name}". Call reset() between registrations.`);
+        }
+        this.#requestHandlers.set(name, callback);
+    }
+    request(name, data, timeoutMs = 5000) {
+        const handler = this.#requestHandlers.get(name);
+        if (!handler) {
+            return Promise.reject(new Error(`FakeBus: no request handler registered for "${name}"`));
+        }
+        // Only log requests the bus accepted. A handler-missing rejection
+        // represents "code-under-test attempted a request the system was
+        // not configured for" — that's a setup bug, not a bus call, and it
+        // should not poison `getRequests()` symmetry with `getEmitted()`.
+        const { parsedData } = parseEmitData(data);
+        this.#requests.push({ kind: 'request', name, data, parsedData });
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new Error(`FakeBus.request: handler for "${name}" did not reply within ${timeoutMs}ms`));
+            }, timeoutMs);
+            // Fake-timers note: `vi.useFakeTimers()` mocks the `setTimeout`
+            // scheduled above. The happy-path resolve via `reply(...)` does
+            // not depend on timer advancement, but the rejection branch does
+            // — call `vi.advanceTimersByTime(timeoutMs)` to surface the
+            // timeout when fake timers are active.
+            const reply = (response) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(response);
+            };
+            const onError = (err) => {
+                if (settled) {
+                    console.error(`[FakeBus] request handler for "${name}" threw after reply:`, err);
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            };
+            try {
+                const ret = handler(data, reply);
+                if (isThenable(ret))
+                    ret.then(undefined, onError);
+            }
+            catch (err) {
+                onError(err);
+            }
+        });
+    }
+    matchesWildcard(pattern, eventName) {
+        return wildcardMatches(pattern, eventName);
+    }
+    subscriptionCount() {
+        return Promise.resolve(this.#subscribers.size);
+    }
+    /**
+     * Defensive clone of the captured emits. **Clone is lossy** for
+     * non-cloneable values: `structuredClone` is tried first, JSON
+     * round-trip is the fallback. BigInt, functions, and other
+     * non-stringifiable payloads collapse to `undefined` in the fallback
+     * path (with a `[FakeBus] non-cloneable capture` `console.warn`).
+     * Internal assertions (`assertEmitted` etc.) read the live capture,
+     * not the clone, so this caveat only affects external readers.
+     */
+    getEmitted() {
+        return this.#emitted.map(cloneEmit);
+    }
+    /** See `getEmitted` — same lossy-clone caveat for non-cloneable values. */
+    getRequests() {
+        return this.#requests.map(cloneRequest);
+    }
+    reset() {
+        this.#emitted = [];
+        this.#requests = [];
+        this.#subscribers.clear();
+        this.#requestHandlers.clear();
+        this.#nextSubId = 1;
+    }
+    assertEmitted(name, predicate) {
+        const match = makeMatcher(name, predicate);
+        if (this.#emitted.some(match))
+            return;
+        throw new Error(`FakeBus.assertEmitted('${name}'${describePredicate(predicate)}) failed — no captured emit matches.\n${describeCaptured(this.#emitted)}`);
+    }
+    assertNotEmitted(name, predicate) {
+        const match = makeMatcher(name, predicate);
+        if (!this.#emitted.some(match))
+            return;
+        throw new Error(`FakeBus.assertNotEmitted('${name}'${describePredicate(predicate)}) failed — at least one captured emit matches.\n${describeCaptured(this.#emitted)}`);
+    }
+}
+/** Port of `wildcard_matches` from `crates/ream-events/src/router.rs`.
+ *  Authoritative source is the Rust router; any divergence is a bug. */
+function wildcardMatches(pattern, eventName) {
+    if (pattern === '**')
+        return true;
+    if (pattern === '*')
+        return !eventName.includes('.');
+    const patternParts = pattern.split('.');
+    const nameParts = eventName.split('.');
+    const last = patternParts[patternParts.length - 1];
+    if (last === '**') {
+        const prefix = patternParts.slice(0, patternParts.length - 1);
+        if (nameParts.length < prefix.length)
+            return false;
+        for (let i = 0; i < prefix.length; i += 1) {
+            if (prefix[i] !== nameParts[i])
+                return false;
+        }
+        return true;
+    }
+    if (patternParts.length !== nameParts.length)
+        return false;
+    for (let i = 0; i < patternParts.length; i += 1) {
+        const p = patternParts[i];
+        if (p !== '*' && p !== nameParts[i])
+            return false;
+    }
+    return true;
+}
+function parseEmitData(data) {
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { parsedData: parsed };
+    }
+    return {
+        parsedData: parsed,
+        correlationId: readStringField(parsed, 'correlationId'),
+        causationId: readStringField(parsed, 'causationId'),
+    };
+}
+function readStringField(source, key) {
+    const record = source;
+    const value = record[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function buildEventJson(entry) {
+    // Mirror the Rust `Event` envelope shape (`crates/ream-events/src/event.rs` —
+    // serde `rename_all = "camelCase"`): `{ id, name, data, correlationId,
+    // causationId?, timestamp, sourceService, nodeId, ttl }`. `data` stays the
+    // raw payload string the caller passed to `emit`, so subscribers using
+    // `JSON.parse(event.data)` after `JSON.parse(eventJson)` work the same
+    // against the fake as against the real bus. The five envelope-metadata
+    // fields (`id`, `timestamp`, `sourceService`, `nodeId`, `ttl`) are
+    // stubbed to the same defaults `Event::new` sets in Rust — synthetic but
+    // type-shape complete, so code-under-test reading them does not branch
+    // differently fake-vs-prod.
+    const generatedId = globalThis.crypto.randomUUID();
+    const envelope = {
+        id: generatedId,
+        name: entry.name,
+        data: entry.data,
+        correlationId: entry.correlationId ?? generatedId,
+        timestamp: new Date().toISOString(),
+        sourceService: '',
+        nodeId: 'local',
+        ttl: 255,
+    };
+    if (entry.causationId !== undefined)
+        envelope.causationId = entry.causationId;
+    return JSON.stringify(envelope);
+}
+function cloneEmit(entry) {
+    try {
+        return structuredClone(entry);
+    }
+    catch {
+        console.warn(`[FakeBus] non-cloneable capture for "${entry.name}"; falling back to JSON round-trip.`);
+        return {
+            kind: 'emit',
+            name: entry.name,
+            data: entry.data,
+            parsedData: cloneViaJson(entry.parsedData),
+            correlationId: entry.correlationId,
+            causationId: entry.causationId,
+        };
+    }
+}
+function cloneRequest(entry) {
+    try {
+        return structuredClone(entry);
+    }
+    catch {
+        console.warn(`[FakeBus] non-cloneable capture for "${entry.name}"; falling back to JSON round-trip.`);
+        return {
+            kind: 'request',
+            name: entry.name,
+            data: entry.data,
+            parsedData: cloneViaJson(entry.parsedData),
+        };
+    }
+}
+function cloneViaJson(value) {
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+function makeMatcher(name, predicate) {
+    if (typeof predicate === 'function') {
+        return (e) => wildcardMatches(name, e.name) && predicate(e);
+    }
+    if (predicate === undefined) {
+        return (e) => wildcardMatches(name, e.name);
+    }
+    return (e) => {
+        if (!wildcardMatches(name, e.name))
+            return false;
+        if (predicate.name !== undefined && !wildcardMatches(predicate.name, e.name))
+            return false;
+        if (predicate.correlationId !== undefined && e.correlationId !== predicate.correlationId)
+            return false;
+        if (predicate.causationId !== undefined && e.causationId !== predicate.causationId)
+            return false;
+        if (predicate.dataMatches) {
+            const arg = e.parsedData !== undefined ? e.parsedData : e.data;
+            if (!predicate.dataMatches(arg))
+                return false;
+        }
+        return true;
+    };
+}
+function describePredicate(predicate) {
+    if (predicate === undefined)
+        return '';
+    if (typeof predicate === 'function')
+        return ', <function predicate>';
+    if (Object.keys(predicate).length === 0) {
+        return ', <empty predicate>';
+    }
+    return `, ${safeStringify(predicate)}`;
+}
+function describeCaptured(captured) {
+    if (captured.length === 0)
+        return 'Captured: (none)';
+    const lines = captured.map((c, i) => `  [${i}] name="${c.name}" data=${safeStringify(c.parsedData ?? c.data)}` +
+        (c.correlationId !== undefined ? ` correlationId="${c.correlationId}"` : '') +
+        (c.causationId !== undefined ? ` causationId="${c.causationId}"` : ''));
+    return `Captured (${captured.length}):\n${lines.join('\n')}`;
+}
+function safeStringify(value) {
+    // JSON.stringify already detects true cycles and throws TypeError —
+    // the outer catch handles that. A previous manual WeakSet walk
+    // mis-labelled DAG sibling references as `<circular>` because it
+    // never released entries on subtree exit.
+    try {
+        return JSON.stringify(value, (_key, v) => {
+            if (typeof v === 'function')
+                return '<function>';
+            // JSON.stringify throws on BigInt; preserve the value lossy-but-
+            // readable so a single BigInt in a captured payload does not
+            // collapse the whole failure message to "<unstringifiable>".
+            if (typeof v === 'bigint')
+                return `${v}n`;
+            return v;
+        });
+    }
+    catch {
+        return '<unstringifiable>';
+    }
+}
+function isThenable(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (!('then' in value))
+        return false;
+    return typeof value.then === 'function';
+}
+//# sourceMappingURL=FakeBus.js.map

package/dist/events/testing/FakeBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeBus.js","sourceRoot":"","sources":["../../../src/events/testing/FakeBus.ts"],"names":[],"mappings":"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"}

package/dist/graphql/GraphQLEngine.d.ts

@@ -0,0 +1,69 @@
+/**
+ * GraphQLEngine — schema-first GraphQL with Rust query validation.
+ *
+ * - Schema parsed from .graphql files at boot
+ * - Queries validated by Rust before NAPI crossing (when available)
+ * - Resolvers are IoC-injected controller-like classes
+ * - @Guard/@Role enforced per TOP-LEVEL resolver field (nested fields are
+ *   projected from the resolver's return value, not independently resolved —
+ *   so they carry no per-field guard; don't return guarded data from an
+ *   unguarded resolver and rely on a nested field guard to hide it).
+ * - The response is pruned to the client's selection set, so a resolver may
+ *   safely return a rich object (e.g. an ORM entity): fields the client did
+ *   not select are dropped before serialization.
+ * - Zero non-null assertions — types guaranteed by schema validation
+ *
+ * Usage:
+ *   const engine = new GraphQLEngine({ schemaPath: './app/graphql/schema.graphql' })
+ *   engine.resolver('Query', 'tasks', TaskResolver, 'tasks')
+ *   engine.resolver('Mutation', 'createTask', TaskResolver, 'createTask', { guard: 'jwt', role: 'cs_member' })
+ *
+ * @implements MISS-28
+ */
+import type { HttpContext } from '../http/HttpContext.js';
+export interface GraphQLConfig {
+    /** Path to .graphql schema file. */
+    schemaPath: string;
+    /** Endpoint path (default: /graphql). */
+    path?: string;
+    /** Enable playground/introspection in dev (default: true when NODE_ENV !== 'production'). */
+    playground?: boolean;
+}
+export interface ResolverOptions {
+    guard?: string;
+    guards?: string[];
+    role?: string;
+    roles?: string[];
+    permissions?: string[];
+}
+/** A parsed field with its (possibly nested) selection set. */
+export interface SelectionField {
+    name: string;
+    alias?: string;
+    args: Record<string, unknown>;
+    selection: SelectionField[];
+}
+export declare class GraphQLEngine {
+    #private;
+    readonly path: string;
+    constructor(config: GraphQLConfig);
+    /** Set IoC container for resolver instantiation. */
+    useContainer(container: {
+        make<T>(target: new (...args: unknown[]) => T): T;
+    }): void;
+    /** Register a resolver for a type.field. */
+    resolver(typeName: string, fieldName: string, handlerClass: new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>, methodName: string, options?: ResolverOptions): void;
+    /** Handle a GraphQL HTTP request. */
+    handle(ctx: HttpContext): Promise<void>;
+    /** Get the raw schema source for introspection. */
+    getSchemaSource(): string;
+}
+/**
+ * Project a resolver result onto the client's selection set. A field with an
+ * empty selection (a scalar leaf) is returned untouched; an object is reduced
+ * to only the selected keys (recursing into nested selections); an array maps
+ * the projection over its items. This is what stops a resolver that returns a
+ * rich object (ORM entity, etc.) from leaking unselected fields.
+ */
+export declare function pruneToSelection(value: unknown, selection: SelectionField[]): unknown;
+//# sourceMappingURL=GraphQLEngine.d.ts.map

package/dist/graphql/GraphQLEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphQLEngine.d.ts","sourceRoot":"","sources":["../../src/graphql/GraphQLEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAoDzD,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAgBD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,SAAS,EAAE,cAAc,EAAE,CAAA;CAC5B;AAED,qBAAa,aAAa;;IAIxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAGT,MAAM,EAAE,aAAa;IASjC,oDAAoD;IACpD,YAAY,CAAC,SAAS,EAAE;QAAE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;KAAE,GAAG,IAAI;IAIpF,4CAA4C;IAC5C,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,EACzF,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,eAAe,GACxB,IAAI;IAWP,qCAAqC;IAC/B,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAoN7C,mDAAmD;IACnD,eAAe,IAAI,MAAM;CAG1B;AA8BD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAWrF"}