@terreno/api 0.20.2 → 0.22.0

package/dist/realtime/changeStreamWatcher.js

@@ -120,7 +120,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stopChangeStreamWatcher = exports.startChangeStreamWatcher = exports.emitToDocumentAndQueryRooms = exports.emitToAuthorizedRoom = exports.serializeDoc = exports.ensureApiId = exports.resolveRooms = exports.mapOperationType = void 0;
-// biome-ignore-all lint/suspicious/noExplicitAny: change stream and socket handlers use dynamic document shapes
 var Sentry = __importStar(require("@sentry/bun"));
 var luxon_1 = require("luxon");
 var mongoose_1 = __importDefault(require("mongoose"));
@@ -208,7 +207,6 @@ var canReadDocument = function (entry, user, doc) { return __awaiter(void 0, voi
  * Exported for testing.
  */
 var resolveRooms = function (entry, doc, method) {
-    var _a, _b, _c;
     var roomStrategy = entry.config.roomStrategy;
     // Use the collection tag (e.g. "todos") for model rooms, matching what the frontend subscribes to
     var collectionTag = getCollectionTag(entry.routePath);
@@ -219,7 +217,7 @@ var resolveRooms = function (entry, doc, method) {
     }
     switch (roomStrategy) {
         case "owner": {
-            var ownerId = (_c = (_b = (_a = doc === null || doc === void 0 ? void 0 : doc.ownerId) === null || _a === void 0 ? void 0 : _a.toString) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : doc === null || doc === void 0 ? void 0 : doc.ownerId;
+            var ownerId = (doc === null || doc === void 0 ? void 0 : doc.ownerId) != null ? String(doc.ownerId) : undefined;
             if (ownerId) {
                 return ["user:".concat(ownerId)];
             }
@@ -625,7 +623,7 @@ var startChangeStreamWatcher = function (io, config, debug) {
                             }
                         }
                         else {
-                            rooms = (0, exports.resolveRooms)(entry, fullDocument, method);
+                            rooms = (0, exports.resolveRooms)(entry, fullDocument !== null && fullDocument !== void 0 ? fullDocument : {}, method);
                         }
                         collection = getCollectionTag(entry.routePath);
                         event_1 = __assign({ collection: collection, id: docId, method: method, model: entry.modelName, timestamp: luxon_1.DateTime.now().toMillis() }, (change.operationType === "update" && ((_e = change.updateDescription) === null || _e === void 0 ? void 0 : _e.updatedFields)

package/dist/realtime/queryMatcher.d.ts

@@ -11,4 +11,4 @@
  * @param query - MongoDB-style query object
  * @returns true if the document matches all query conditions
  */
-export declare const matchesQuery: (doc: any, query: Record<string, any>) => boolean;
+export declare const matchesQuery: (doc: Record<string, unknown>, query: Record<string, unknown>) => boolean;

package/dist/realtime/queryMatcher.js

@@ -1,5 +1,4 @@
 "use strict";
-// biome-ignore-all lint/suspicious/noExplicitAny: MongoDB query matcher evaluates dynamic filter shapes
 /**
  * Simple in-memory MongoDB query matcher.
  * Evaluates a MongoDB-style query object against a document without hitting the database.
@@ -63,14 +62,32 @@ var normalize = function (value) {
         return value;
     }
     // Handle ObjectId-like objects with toString
-    if (typeof value === "object" &&
-        typeof value.toString === "function" &&
-        ((_a = value.constructor) === null || _a === void 0 ? void 0 : _a.name) !== "Object" &&
-        !Array.isArray(value)) {
-        return value.toString();
+    if (typeof value === "object" && !Array.isArray(value)) {
+        var obj = value;
+        var ctorName = (_a = obj.constructor) === null || _a === void 0 ? void 0 : _a.name;
+        if (typeof obj.toString === "function" && ctorName !== "Object") {
+            return String(value);
+        }
     }
     return value;
 };
+/**
+ * JS abstract relational comparison on unknown values.
+ * Numeric operands compare numerically; everything else compares as strings.
+ * This mirrors the coercion behaviour of `>` / `<` on the `any`-typed values
+ * that MongoDB in-memory matching historically received.
+ */
+var compareValues = function (a, b) {
+    if (typeof a === "number" && typeof b === "number") {
+        return a - b;
+    }
+    if (typeof a === "string" && typeof b === "string") {
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    var numA = Number(a);
+    var numB = Number(b);
+    return numA - numB;
+};
 var matchesCondition = function (rawValue, condition) {
     var e_2, _a;
     var value = normalize(rawValue);
@@ -99,26 +116,34 @@ var matchesCondition = function (rawValue, condition) {
                         return false;
                     }
                     break;
-                case "$gt":
-                    if (!(value > normOp)) {
+                case "$gt": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp <= 0) {
                         return false;
                     }
                     break;
-                case "$gte":
-                    if (!(value >= normOp)) {
+                }
+                case "$gte": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp < 0) {
                         return false;
                     }
                     break;
-                case "$lt":
-                    if (!(value < normOp)) {
+                }
+                case "$lt": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp >= 0) {
                         return false;
                     }
                     break;
-                case "$lte":
-                    if (!(value <= normOp)) {
+                }
+                case "$lte": {
+                    var cmp = compareValues(value, normOp);
+                    if (Number.isNaN(cmp) || cmp > 0) {
                         return false;
                     }
                     break;
+                }
                 case "$in": {
                     if (!Array.isArray(operand)) {
                         return false;

package/dist/realtime/types.d.ts

@@ -13,9 +13,9 @@ export interface RealtimeConfig {
      * - 'broadcast': emit to all authenticated sockets
      * - function: custom room resolver returning room name(s)
      */
-    roomStrategy: "owner" | "model" | "broadcast" | ((doc: any, method: string, req: express.Request) => string[]);
+    roomStrategy: "owner" | "model" | "broadcast" | ((doc: Record<string, unknown>, method: string, req: express.Request) => string[]);
     /** Custom serializer for real-time events. Falls back to the modelRouter responseHandler. */
-    realtimeResponseHandler?: (doc: any, method: string) => any;
+    realtimeResponseHandler?: (doc: Record<string, unknown>, method: string) => unknown;
 }
 /**
  * A real-time sync event emitted to clients via WebSocket.
@@ -94,7 +94,7 @@ export interface QuerySubscription {
     /** Collection tag (e.g. "todos") */
     collection: string;
     /** MongoDB-style query filter (e.g. {completed: false}) */
-    query: Record<string, any>;
+    query: Record<string, unknown>;
     /** Client-provided queryId (ignored — server computes a canonical ID) */
     queryId?: string;
 }

package/dist/requestContext.d.ts

@@ -1,15 +1,32 @@
 import type express from "express";
 import type { JwtPayload } from "jsonwebtoken";
+/**
+ * Correlation fields stored in AsyncLocalStorage for the lifetime of a request or job. Every log
+ * line emitted inside the scope is enriched with these. `requestId` is the only required field; the
+ * rest are populated when headers, trace context, or auth supply them.
+ */
 export interface RequestContext {
+    /** Background job identifier (from `x-job-id` or set via {@link runWithRequestContext}). */
     jobId?: string;
+    /** Stable id shared by all log lines for one request/job; echoed to clients as `X-Request-ID`. */
     requestId: string;
+    /** Auth session id, resolved from the JWT/Better Auth session or `x-session-id`. */
     sessionId?: string;
+    /** Distributed-tracing span id, parsed from Cloud Trace or W3C `traceparent`. */
     spanId?: string;
+    /** Distributed-tracing trace id, parsed from Cloud Trace or W3C `traceparent`. */
     traceId?: string;
+    /** Whether the trace is sampled, per the incoming trace headers. */
     traceSampled?: boolean;
+    /** Authenticated user id, populated after auth middleware runs. */
     userId?: string;
 }
 export type RequestContextAttributes = Record<string, string>;
+/**
+ * Canonical HTTP header names for each correlation field. Use these to propagate context to
+ * downstream services (pair with {@link getCurrentRequestContextAttributes}) or to read it from an
+ * incoming request (pair with {@link getRequestContextFromAttributes}).
+ */
 export declare const REQUEST_CONTEXT_ATTRIBUTE_NAMES: {
     readonly jobId: "x-job-id";
     readonly requestId: "x-request-id";
@@ -26,12 +43,56 @@ export interface JwtSessionPayload extends JwtPayload {
 }
 export declare const getSessionIdFromJwtPayload: (payload?: JwtSessionPayload | null) => string | undefined;
 export declare const getRequestContextFromAttributes: (attributes?: Record<string, string | undefined>) => RequestContext;
+/**
+ * Returns the full {@link RequestContext} for the active AsyncLocalStorage scope, or `undefined`
+ * when called outside any request/job scope. The logger uses this to enrich each line.
+ */
 export declare const getCurrentRequestContext: () => RequestContext | undefined;
+/**
+ * Returns the active correlation fields as a plain object (empty when outside a scope). This is the
+ * shape attached to Sentry log attributes and is handy when you need to log or forward the current
+ * context yourself.
+ */
 export declare const getCurrentLogContext: () => Partial<RequestContext>;
 export declare const applyRequestContextToSentry: (context?: Partial<RequestContext>) => void;
 export declare const setRequestContext: (updates: Partial<RequestContext>) => void;
+/**
+ * Serializes the active correlation context into HTTP header attributes (keyed by
+ * {@link REQUEST_CONTEXT_ATTRIBUTE_NAMES}) so it can be propagated on outbound requests to other
+ * services, keeping the same `requestId`/`traceId` across service boundaries.
+ */
 export declare const getCurrentRequestContextAttributes: (overrides?: Partial<RequestContext>) => RequestContextAttributes;
+/**
+ * Runs `callback` inside a fresh correlation scope so every log line it emits shares the same
+ * identifiers — the manual equivalent of {@link requestContextMiddleware} for background jobs,
+ * cron tasks, scripts, queue consumers, etc. A `requestId` is generated when not supplied, and the
+ * context is mirrored to Sentry.
+ *
+ * @example
+ * ```typescript
+ * import {createScopedLogger, runWithRequestContext} from "@terreno/api";
+ *
+ * await runWithRequestContext({jobId: "nightly-sync"}, async () => {
+ *   const log = createScopedLogger({prefix: "[NightlySync]"});
+ *   log.info("started"); // includes jobId + a generated requestId on every line
+ *   await sync();
+ * });
+ * ```
+ */
 export declare const runWithRequestContext: <T>(context: Partial<RequestContext>, callback: () => T) => T;
+/**
+ * Like {@link runWithRequestContext}, but seeds the scope from raw header attributes (for example
+ * those received on an incoming message or forwarded by another service). Parses Cloud Trace / W3C
+ * `traceparent` into `traceId`/`spanId` via {@link getRequestContextFromAttributes}.
+ */
 export declare const runWithRequestContextAttributes: <T>(attributes: Record<string, string | undefined> | undefined, callback: () => T) => T;
 export declare const updateRequestContextFromRequest: (req: express.Request, res?: express.Response) => void;
+/**
+ * Express middleware that opens a correlation scope for the request. Mounted early by `TerrenoApp` /
+ * `setupServer`, it resolves a `requestId` (from request-id/correlation headers, Cloud Trace, or
+ * W3C `traceparent`, else a new UUID), captures any `jobId`/`sessionId`/trace fields, echoes
+ * `X-Request-ID` back to the client, and runs the remaining middleware inside the scope so all
+ * downstream logs are correlated. A later auth-aware pass ({@link updateRequestContextFromRequest})
+ * fills in `userId`/`sessionId`.
+ */
 export declare const requestContextMiddleware: (req: express.Request, res: express.Response, next: express.NextFunction) => void;

package/dist/requestContext.js

@@ -72,6 +72,31 @@ var __values = (this && this.__values) || function(o) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestContextMiddleware = exports.updateRequestContextFromRequest = exports.runWithRequestContextAttributes = exports.runWithRequestContext = exports.getCurrentRequestContextAttributes = exports.setRequestContext = exports.applyRequestContextToSentry = exports.getCurrentLogContext = exports.getCurrentRequestContext = exports.getRequestContextFromAttributes = exports.getSessionIdFromJwtPayload = exports.REQUEST_CONTEXT_ATTRIBUTE_NAMES = void 0;
+/**
+ * Request/job correlation for `@terreno/api`.
+ *
+ * Correlation is how every log line emitted while handling one request (or one background job) can
+ * be tied back together. It is built on Node's {@link AsyncLocalStorage}: a {@link RequestContext}
+ * (with `requestId`, `userId`, `traceId`, etc.) is stored for the duration of a callback, and the
+ * logger's Winston format reads it from there and merges it into each line. Nothing needs to be
+ * threaded through function arguments.
+ *
+ * Two ways a scope is established:
+ *
+ * - **HTTP**: {@link requestContextMiddleware} runs first in the middleware stack. It derives a
+ *   `requestId` from incoming headers ({@link REQUEST_CONTEXT_ATTRIBUTE_NAMES}, `x-correlation-id`,
+ *   Cloud Trace, or W3C `traceparent`) or generates one, echoes it back as `X-Request-ID`, and runs
+ *   the rest of the request inside the scope.
+ * - **Jobs/scripts**: {@link runWithRequestContext} (or {@link runWithRequestContextAttributes})
+ *   establishes the same scope manually so background work is just as traceable.
+ *
+ * The active context is also pushed to Sentry tags/context via {@link applyRequestContextToSentry},
+ * and is exposed to logging via {@link getCurrentLogContext} / {@link getCurrentRequestContext}.
+ *
+ * @see {@link runWithRequestContext}
+ * @see {@link getCurrentLogContext}
+ * @module requestContext
+ */
 var node_async_hooks_1 = require("node:async_hooks");
 var node_crypto_1 = require("node:crypto");
 var Sentry = __importStar(require("@sentry/bun"));
@@ -84,6 +109,11 @@ var TRACE_ID_HEADER = "x-trace-id";
 var TRACE_PARENT_HEADER = "traceparent";
 var TRACE_SAMPLED_HEADER = "x-trace-sampled";
 var USER_ID_HEADER = "x-user-id";
+/**
+ * Canonical HTTP header names for each correlation field. Use these to propagate context to
+ * downstream services (pair with {@link getCurrentRequestContextAttributes}) or to read it from an
+ * incoming request (pair with {@link getRequestContextFromAttributes}).
+ */
 exports.REQUEST_CONTEXT_ATTRIBUTE_NAMES = {
     jobId: JOB_ID_HEADER,
     requestId: "x-request-id",
@@ -193,10 +223,19 @@ var getRequestContextFromAttributes = function (attributes) {
     };
 };
 exports.getRequestContextFromAttributes = getRequestContextFromAttributes;
+/**
+ * Returns the full {@link RequestContext} for the active AsyncLocalStorage scope, or `undefined`
+ * when called outside any request/job scope. The logger uses this to enrich each line.
+ */
 var getCurrentRequestContext = function () {
     return requestContextStorage.getStore();
 };
 exports.getCurrentRequestContext = getCurrentRequestContext;
+/**
+ * Returns the active correlation fields as a plain object (empty when outside a scope). This is the
+ * shape attached to Sentry log attributes and is handy when you need to log or forward the current
+ * context yourself.
+ */
 var getCurrentLogContext = function () {
     var context = (0, exports.getCurrentRequestContext)();
     if (!context) {
@@ -266,6 +305,11 @@ var setAttribute = function (attributes, name, value) {
     }
     attributes[name] = String(value);
 };
+/**
+ * Serializes the active correlation context into HTTP header attributes (keyed by
+ * {@link REQUEST_CONTEXT_ATTRIBUTE_NAMES}) so it can be propagated on outbound requests to other
+ * services, keeping the same `requestId`/`traceId` across service boundaries.
+ */
 var getCurrentRequestContextAttributes = function (overrides) {
     if (overrides === void 0) { overrides = {}; }
     var context = __assign(__assign({}, (0, exports.getCurrentLogContext)()), overrides);
@@ -280,6 +324,23 @@ var getCurrentRequestContextAttributes = function (overrides) {
     return attributes;
 };
 exports.getCurrentRequestContextAttributes = getCurrentRequestContextAttributes;
+/**
+ * Runs `callback` inside a fresh correlation scope so every log line it emits shares the same
+ * identifiers — the manual equivalent of {@link requestContextMiddleware} for background jobs,
+ * cron tasks, scripts, queue consumers, etc. A `requestId` is generated when not supplied, and the
+ * context is mirrored to Sentry.
+ *
+ * @example
+ * ```typescript
+ * import {createScopedLogger, runWithRequestContext} from "@terreno/api";
+ *
+ * await runWithRequestContext({jobId: "nightly-sync"}, async () => {
+ *   const log = createScopedLogger({prefix: "[NightlySync]"});
+ *   log.info("started"); // includes jobId + a generated requestId on every line
+ *   await sync();
+ * });
+ * ```
+ */
 var runWithRequestContext = function (context, callback) {
     var _a;
     var nextContext = __assign(__assign({}, context), { requestId: (_a = context.requestId) !== null && _a !== void 0 ? _a : (0, node_crypto_1.randomUUID)() });
@@ -289,6 +350,11 @@ var runWithRequestContext = function (context, callback) {
     });
 };
 exports.runWithRequestContext = runWithRequestContext;
+/**
+ * Like {@link runWithRequestContext}, but seeds the scope from raw header attributes (for example
+ * those received on an incoming message or forwarded by another service). Parses Cloud Trace / W3C
+ * `traceparent` into `traceId`/`spanId` via {@link getRequestContextFromAttributes}.
+ */
 var runWithRequestContextAttributes = function (attributes, callback) {
     if (attributes === void 0) { attributes = {}; }
     return (0, exports.runWithRequestContext)((0, exports.getRequestContextFromAttributes)(attributes), callback);
@@ -312,6 +378,14 @@ var updateRequestContextFromRequest = function (req, res) {
     }
 };
 exports.updateRequestContextFromRequest = updateRequestContextFromRequest;
+/**
+ * Express middleware that opens a correlation scope for the request. Mounted early by `TerrenoApp` /
+ * `setupServer`, it resolves a `requestId` (from request-id/correlation headers, Cloud Trace, or
+ * W3C `traceparent`, else a new UUID), captures any `jobId`/`sessionId`/trace fields, echoes
+ * `X-Request-ID` back to the client, and runs the remaining middleware inside the scope so all
+ * downstream logs are correlated. A later auth-aware pass ({@link updateRequestContextFromRequest})
+ * fills in `userId`/`sessionId`.
+ */
 var requestContextMiddleware = function (req, res, next) {
     var cloudTraceContext = parseGoogleCloudTraceContext(getHeader(req, CLOUD_TRACE_CONTEXT_HEADER));
     var traceParentContext = parseTraceParent(getHeader(req, TRACE_PARENT_HEADER));