dataceen-client 0.0.1

package/dist/subscriptions/subscription-manager.js

@@ -0,0 +1,211 @@
+import { openSubscriptionStream } from "./grpc-client.js";
+import * as grpc from "@grpc/grpc-js";
+/**
+ * Run the subscription: open a gRPC stream, read events, dispatch to handlers,
+ * reconnect on transient errors, exit cleanly when the subscription is cancelled.
+ */
+export async function runSubscription(subscription, opts) {
+    const slowMs = opts.slowHandlerThresholdMs ?? 500;
+    const maxReconnects = opts.maxReconnectAttempts ?? 10;
+    const baseReconnectMs = opts.reconnectBaseMs ?? 1000;
+    let reconnectDelay = baseReconnectMs;
+    while (!subscription.signal.aborted) {
+        const token = await opts.tokenProvider.getAccessToken([opts.subscriptionScope]);
+        const stream = openSubscriptionStream({
+            subscriptionUrl: opts.subscriptionUrl,
+            accessToken: token,
+            request: subscription.request,
+        });
+        const cancelOnAbort = () => stream.cancel();
+        subscription.signal.addEventListener("abort", cancelOnAbort, { once: true });
+        try {
+            await readStream(stream, subscription, opts.logger, slowMs);
+            // Stream ended cleanly (server closed) — exit
+            subscription.signal.removeEventListener("abort", cancelOnAbort);
+            return;
+        }
+        catch (err) {
+            subscription.signal.removeEventListener("abort", cancelOnAbort);
+            if (subscription.signal.aborted) {
+                // Normal shutdown
+                return;
+            }
+            const isCancelled = isRpcCancelled(err);
+            if (isCancelled)
+                return;
+            subscription.retryCount++;
+            if (subscription.retryCount > maxReconnects) {
+                opts.logger.log("error", `Subscription ${subscription.id} exceeded ${maxReconnects} reconnect attempts, giving up.`, err);
+                throw err;
+            }
+            // Dispatch a synthetic CONNECTION_LOST event to every handler so apps can react.
+            const lostEvt = syntheticEvent("CONNECTION_LOST", subscription);
+            await dispatchToAll(subscription, lostEvt, opts.logger, slowMs);
+            opts.logger.log("warn", `Subscription ${subscription.id} stream error (attempt ${subscription.retryCount}/${maxReconnects}): ${errorMessage(err)}. Reconnecting in ${reconnectDelay}ms.`);
+            await delay(reconnectDelay);
+            reconnectDelay = Math.min(reconnectDelay * 2, 60_000);
+            // Mutate the request so the next iteration resumes instead of restarting
+            // from scratch (avoids re-running the entire baseload after a transient
+            // drop). Mirrors DataceenClient.cs:ConnectionLostAsync.
+            prepareRequestForReconnect(subscription);
+        }
+    }
+}
+function prepareRequestForReconnect(subscription) {
+    const req = subscription.request;
+    const lastPos = subscription.lastPosition;
+    if (subscription.isBaseLoading) {
+        req.baseloadContinueObjectType = subscription.baseloadLabel;
+        if (lastPos)
+            req.position = lastPos;
+    }
+    else {
+        req.baseloadTopics = [];
+        req.baseloadContinueObjectType = "";
+        req.positionBeforeBaseload = "";
+        if (req.startMode === "POSITION_BEGINNING" ||
+            req.startMode === "POSITION_END" ||
+            req.startMode === "POSITION_TIME") {
+            req.startMode = "POSITION_EXACT";
+        }
+        if (lastPos)
+            req.position = lastPos;
+    }
+}
+async function readStream(stream, subscription, logger, slowMs) {
+    for await (const raw of stream) {
+        if (subscription.signal.aborted)
+            break;
+        if (raw.messagetype === "KEEPALIVE")
+            continue;
+        // First event after a retry → emit CONNECTION_RECONNECTED to handlers
+        if (subscription.retryCount > 0) {
+            const reconnectEvt = syntheticEvent("CONNECTION_RECONNECTED", subscription);
+            await dispatchToAll(subscription, reconnectEvt, logger, slowMs);
+            subscription.retryCount = 0;
+        }
+        // Track baseload state
+        const evtType = raw.eventtype;
+        if (evtType === "BASELOAD_END" || evtType === "BASELOAD_STEP_1") {
+            subscription.isBaseLoading = false;
+        }
+        else if (evtType === "BASELOAD_EVENT") {
+            subscription.isBaseLoading = true;
+            subscription.baseloadLabel = raw.topic;
+            subscription.lastPosition = raw.position;
+        }
+        else {
+            subscription.isBaseLoading = false;
+            subscription.lastPosition = raw.position;
+        }
+        const lowLevel = toLowLevelEvent(raw);
+        await dispatchOne(subscription, lowLevel, logger, slowMs);
+    }
+}
+/** @internal exposed for testing */
+export async function dispatchOne(subscription, lowLevel, logger, slowMs) {
+    // Typed handler for this topic (if any)
+    const handler = subscription.getHandler(lowLevel.topic);
+    if (handler) {
+        await invokeTyped(handler, lowLevel, logger, slowMs);
+    }
+    // All low-level handlers
+    for (const lh of subscription.getLowLevelHandlers()) {
+        await runWithTiming(logger, slowMs, `low-level handler (topic=${lowLevel.topic})`, () => lh(lowLevel));
+    }
+}
+async function dispatchToAll(subscription, lowLevel, logger, slowMs) {
+    for (const [topic, handler] of subscription.getAllHandlers()) {
+        await invokeTyped(handler, { ...lowLevel, topic }, logger, slowMs);
+    }
+    for (const lh of subscription.getLowLevelHandlers()) {
+        await runWithTiming(logger, slowMs, `low-level handler (synthetic ${lowLevel.eventType})`, () => lh(lowLevel));
+    }
+}
+async function invokeTyped(handler, lowLevel, logger, slowMs) {
+    let parsed = undefined;
+    if (lowLevel.complete && lowLevel.complete.length > 0) {
+        try {
+            parsed = JSON.parse(lowLevel.complete);
+        }
+        catch (err) {
+            logger.log("warn", `Subscription event for topic ${lowLevel.topic} had unparseable 'complete' payload`, err);
+        }
+    }
+    const typed = { ...lowLevel, complete: parsed };
+    await runWithTiming(logger, slowMs, `typed handler (topic=${lowLevel.topic})`, () => handler(typed));
+}
+async function runWithTiming(logger, slowMs, label, action) {
+    const start = Date.now();
+    try {
+        await action();
+    }
+    catch (err) {
+        logger.log("error", `Handler threw (${label})`, err);
+        return;
+    }
+    const elapsed = Date.now() - start;
+    if (elapsed > slowMs) {
+        logger.log("warn", `Slow ${label}: ${elapsed}ms`);
+    }
+}
+/** @internal exposed for testing */
+export function toLowLevelEvent(raw) {
+    return {
+        position: raw.position,
+        eventDateTime: eventTimeToIso(raw.eventtime),
+        operationType: raw.operationtype,
+        clientId: raw.clientid,
+        topic: raw.topic,
+        id: raw.id,
+        fromId: raw.fromid,
+        toId: raw.toid,
+        delta: raw.delta,
+        complete: raw.complete,
+        eventType: raw.eventtype,
+        objectType: raw.objecttype,
+        domain: raw.domain,
+        model: raw.model,
+    };
+}
+function eventTimeToIso(ts) {
+    if (!ts)
+        return "";
+    if (typeof ts === "string")
+        return ts;
+    const seconds = Number(ts.seconds);
+    const ms = seconds * 1000 + Math.floor(ts.nanos / 1_000_000);
+    return new Date(ms).toISOString();
+}
+function syntheticEvent(eventType, subscription) {
+    return {
+        position: subscription.lastPosition,
+        eventDateTime: new Date().toISOString(),
+        operationType: "UPDATE",
+        clientId: "",
+        topic: "",
+        id: "",
+        fromId: "",
+        toId: "",
+        delta: "",
+        complete: "",
+        eventType,
+        objectType: "NODE",
+        domain: subscription.request.domain,
+        model: subscription.request.model,
+    };
+}
+function isRpcCancelled(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const e = err;
+    return e.code === grpc.status.CANCELLED || e.code === "CANCELLED";
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/subscriptions/subscription.d.ts

@@ -0,0 +1,43 @@
+import type { EventHandler, LowLevelEventHandler, SubscriptionRequest } from "./types.js";
+/**
+ * A subscription — a collection of per-topic typed handlers plus optional
+ * low-level handlers, all sharing a single gRPC stream.
+ *
+ * The lifetime pattern matches the C# Subscription class:
+ *   const sub = dataceen.createSubscription(request);
+ *   sub.on<Customer>("Customer", handler);
+ *   sub.on<Order>("Order", handler);
+ *   await dataceen.subscribe(sub);  // blocks until sub.cancel() or stream ends
+ */
+export declare class Subscription {
+    readonly id: string;
+    readonly request: SubscriptionRequest;
+    /** Server's current position in the event stream — updated as events arrive. */
+    lastPosition: string;
+    /** True while the server is emitting BASELOAD_EVENT items. */
+    isBaseLoading: boolean;
+    /** Topic currently being baseloaded (set by BASELOAD_EVENT, cleared by BASELOAD_STEP_1). */
+    baseloadLabel: string;
+    /** Reconnect attempt counter — used to dispatch CONNECTION_RECONNECTED on first success after a retry. */
+    retryCount: number;
+    private readonly handlers;
+    private readonly lowLevelHandlers;
+    private readonly abortController;
+    constructor(id: string, request: SubscriptionRequest);
+    /** Register a typed handler for a topic (entity type name). Overwrites any prior handler for that topic. */
+    on<T>(topic: string, handler: EventHandler<T>): void;
+    /** Remove the handler for a topic. */
+    off(topic: string): void;
+    /** Register a handler that receives every event in its raw (unparsed) form. */
+    onLowLevel(handler: LowLevelEventHandler): void;
+    /** AbortSignal consumed by the subscription manager. */
+    get signal(): AbortSignal;
+    /** Stop the stream. The subscribe() Promise will resolve cleanly. */
+    cancel(): void;
+    /** @internal */
+    getHandler(topic: string): EventHandler<unknown> | undefined;
+    /** @internal */
+    getAllHandlers(): ReadonlyMap<string, EventHandler<unknown>>;
+    /** @internal */
+    getLowLevelHandlers(): readonly LowLevelEventHandler[];
+}

package/dist/subscriptions/subscription.js

@@ -0,0 +1,61 @@
+/**
+ * A subscription — a collection of per-topic typed handlers plus optional
+ * low-level handlers, all sharing a single gRPC stream.
+ *
+ * The lifetime pattern matches the C# Subscription class:
+ *   const sub = dataceen.createSubscription(request);
+ *   sub.on<Customer>("Customer", handler);
+ *   sub.on<Order>("Order", handler);
+ *   await dataceen.subscribe(sub);  // blocks until sub.cancel() or stream ends
+ */
+export class Subscription {
+    id;
+    request;
+    /** Server's current position in the event stream — updated as events arrive. */
+    lastPosition = "";
+    /** True while the server is emitting BASELOAD_EVENT items. */
+    isBaseLoading = false;
+    /** Topic currently being baseloaded (set by BASELOAD_EVENT, cleared by BASELOAD_STEP_1). */
+    baseloadLabel = "";
+    /** Reconnect attempt counter — used to dispatch CONNECTION_RECONNECTED on first success after a retry. */
+    retryCount = 0;
+    handlers = new Map();
+    lowLevelHandlers = [];
+    abortController = new AbortController();
+    constructor(id, request) {
+        this.id = id;
+        this.request = request;
+    }
+    /** Register a typed handler for a topic (entity type name). Overwrites any prior handler for that topic. */
+    on(topic, handler) {
+        this.handlers.set(topic, handler);
+    }
+    /** Remove the handler for a topic. */
+    off(topic) {
+        this.handlers.delete(topic);
+    }
+    /** Register a handler that receives every event in its raw (unparsed) form. */
+    onLowLevel(handler) {
+        this.lowLevelHandlers.push(handler);
+    }
+    /** AbortSignal consumed by the subscription manager. */
+    get signal() {
+        return this.abortController.signal;
+    }
+    /** Stop the stream. The subscribe() Promise will resolve cleanly. */
+    cancel() {
+        this.abortController.abort();
+    }
+    /** @internal */
+    getHandler(topic) {
+        return this.handlers.get(topic);
+    }
+    /** @internal */
+    getAllHandlers() {
+        return this.handlers;
+    }
+    /** @internal */
+    getLowLevelHandlers() {
+        return this.lowLevelHandlers;
+    }
+}

package/dist/subscriptions/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Subscription types — mirror the Dataceen gRPC proto enums and message shapes.
+ * Wire-format enum values (SCREAMING_SNAKE) are used as TS string-union values
+ * since the proto-loader is configured with `enums: String`.
+ */
+export type StartMode = "POSITION_BEGINNING" | "POSITION_END" | "POSITION_EXACT" | "POSITION_TIME";
+export type MessageType = "NORMAL" | "KEEPALIVE";
+export type EventType = "SUBSCRIPTION_EVENT" | "BASELOAD_EVENT" | "BASELOAD_STEP_1" | "BASELOAD_STEP_1_ALL" | "BASELOAD_END" | "POSITION_AT_START_PASSED" | "CONNECTION_LOST" | "CONNECTION_RECONNECTED";
+export type OperationType = "CREATE" | "UPDATE" | "DELETE";
+export type ObjectType = "NODE" | "RELATIONSHIP";
+/**
+ * Request for opening a subscription stream. Matches the proto
+ * `SubscriptionRequest` message (camelCased here; serialization to
+ * proto field names happens inside the gRPC layer).
+ */
+export interface SubscriptionRequest {
+    domain: string;
+    model: string;
+    scope: string;
+    baseloadTopics?: string[];
+    topics: string[];
+    ids?: string[];
+    startMode?: StartMode;
+    position?: string;
+    startTime?: Date;
+    includeDelta?: boolean;
+    includeComplete?: boolean;
+    baseloadContinueObjectType?: string;
+    positionBeforeBaseload?: string;
+}
+/**
+ * Fields shared by typed and low-level subscription events.
+ * Camel-cased from the proto's lowercase wire names.
+ */
+export interface SubscriptionEventBase {
+    position: string;
+    eventDateTime: string;
+    operationType: OperationType;
+    clientId: string;
+    topic: string;
+    id: string;
+    fromId: string;
+    toId: string;
+    delta: string;
+    eventType: EventType;
+    objectType: ObjectType;
+    domain: string;
+    model: string;
+}
+/**
+ * A subscription event for a specific entity type. `complete` is parsed JSON
+ * when the server included it. Synthetic events (CONNECTION_LOST,
+ * CONNECTION_RECONNECTED, BASELOAD_END, BASELOAD_STEP_1) have `complete = undefined`.
+ */
+export interface SubscriptionEvent<T> extends SubscriptionEventBase {
+    complete: T | undefined;
+}
+/** Raw event with `complete` as the unparsed JSON string. */
+export interface SubscriptionLowLevelEvent extends SubscriptionEventBase {
+    complete: string;
+}
+export type EventHandler<T> = (evt: SubscriptionEvent<T>) => Promise<void> | void;
+export type LowLevelEventHandler = (evt: SubscriptionLowLevelEvent) => Promise<void> | void;

package/dist/subscriptions/types.js

@@ -0,0 +1,6 @@
+/**
+ * Subscription types — mirror the Dataceen gRPC proto enums and message shapes.
+ * Wire-format enum values (SCREAMING_SNAKE) are used as TS string-union values
+ * since the proto-loader is configured with `enums: String`.
+ */
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "dataceen-client",
+  "version": "0.0.1",
+  "description": "TypeScript client for Dataceen GraphQL + subscription APIs",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".":               { "types": "./dist/index.d.ts",               "import": "./dist/index.js" },
+    "./runtime":       { "types": "./dist/runtime/index.d.ts",       "import": "./dist/runtime/index.js" },
+    "./subscriptions": { "types": "./dist/subscriptions/index.d.ts", "import": "./dist/subscriptions/index.js" },
+    "./config":        { "types": "./dist/config.d.ts",              "import": "./dist/config.js" }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "spike:token": "tsx src/spike/01-token.ts",
+    "spike:query": "tsx src/spike/02-graphql-query.ts",
+    "spike:subscribe": "tsx src/spike/03-grpc-subscription.ts",
+    "spike:introspect": "tsx src/spike/04-introspection.ts",
+    "spike:all": "npm run spike:token && npm run spike:query && npm run spike:subscribe",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "RUN_INTEGRATION=1 vitest run",
+    "codegen:schema": "tsx tools/codegen/src/cli-fetch.ts",
+    "codegen:emit": "tsx tools/codegen/src/cli-emit.ts",
+    "codegen": "npm run codegen:schema && npm run codegen:emit",
+    "example:find": "tsx examples/candy-shop/find.ts",
+    "example:search": "tsx examples/candy-shop/search-and-aggregate.ts",
+    "example:subscribe": "tsx examples/candy-shop/subscriber.ts",
+    "example:program": "tsx examples/candy-shop/program.ts"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^2.16.2",
+    "@grpc/grpc-js": "^1.12.5",
+    "@grpc/proto-loader": "^0.7.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "dotenv": "^16.4.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  }
+}