@terreno/api 0.13.3 → 0.14.1

package/dist/plugins.d.ts

@@ -60,19 +60,19 @@ export declare const findExactlyOne: <T>(schema: Schema<T>) => void;
 export declare const upsertPlugin: <T>(schema: Schema<any, any, any, any>) => void;
 /** For models with the upsertPlugin, extend this interface to add the upsert static method. */
 export interface HasUpsert<T> {
-    upsert(conditions: Record<string, any>, update: Record<string, any>): Promise<T>;
+    upsert(conditions: Record<string, unknown>, update: Record<string, unknown>): Promise<T>;
 }
 export interface FindOneOrNonePlugin<T> {
-    findOneOrNone(query: Record<string, any>, errorArgs?: Partial<APIErrorConstructor>): Promise<(Document & T) | null>;
+    findOneOrNone(query: Record<string, unknown>, errorArgs?: Partial<APIErrorConstructor>): Promise<(Document & T) | null>;
 }
 export interface FindExactlyOnePlugin<T> {
-    findExactlyOne(query: Record<string, any>, errorArgs?: Partial<APIErrorConstructor>): Promise<Document & T>;
+    findExactlyOne(query: Record<string, unknown>, errorArgs?: Partial<APIErrorConstructor>): Promise<Document & T>;
 }
 export declare class DateOnly extends SchemaType {
     constructor(key: string, options: SchemaTypeOptions<Date>);
-    handleSingle(val: any): Date | undefined;
+    handleSingle(val: unknown): Date | undefined;
     $conditionalHandlers: any;
-    castForQuery($conditional: any, val: any, context: any): Date | undefined;
+    castForQuery($conditional: string | undefined, val: unknown, context: unknown): Date | undefined;
     cast(val: unknown): Date | undefined;
     get(val: unknown): this;
 }

package/dist/plugins.js

@@ -99,6 +99,7 @@ exports.DateOnly = exports.upsertPlugin = exports.findExactlyOne = exports.findO
 var luxon_1 = require("luxon");
 var mongoose_1 = __importStar(require("mongoose"));
 var errors_1 = require("./errors");
+// biome-ignore lint/suspicious/noExplicitAny: Schema generics must be loose to accept arbitrary consumer schemas
 var baseUserPlugin = function (schema) {
     schema.add({
         admin: { default: false, description: "Whether the user has admin privileges", type: Boolean },
@@ -106,6 +107,7 @@ var baseUserPlugin = function (schema) {
     schema.add({ email: { description: "The user's email address", index: true, type: String } });
 };
 exports.baseUserPlugin = baseUserPlugin;
+// biome-ignore lint/suspicious/noExplicitAny: Schema generics must be loose to accept arbitrary consumer schemas
 var isDeletedPlugin = function (schema, defaultValue) {
     if (defaultValue === void 0) { defaultValue = false; }
     schema.add({
@@ -117,6 +119,7 @@ var isDeletedPlugin = function (schema, defaultValue) {
             type: Boolean,
         },
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Query<any, any> must be loose to accept arbitrary consumer queries
     var applyDeleteFilter = function (q) {
         var query = q.getQuery();
         if (query && query.deleted === undefined) {
@@ -131,7 +134,9 @@ var isDeletedPlugin = function (schema, defaultValue) {
     });
 };
 exports.isDeletedPlugin = isDeletedPlugin;
-var isDisabledPlugin = function (schema, defaultValue) {
+var isDisabledPlugin = function (
+// biome-ignore lint/suspicious/noExplicitAny: Schema generics must be loose to accept arbitrary consumer schemas
+schema, defaultValue) {
     if (defaultValue === void 0) { defaultValue = false; }
     schema.add({
         disabled: {
@@ -143,6 +148,7 @@ var isDisabledPlugin = function (schema, defaultValue) {
     });
 };
 exports.isDisabledPlugin = isDisabledPlugin;
+// biome-ignore lint/suspicious/noExplicitAny: Schema generics must be loose to accept arbitrary consumer schemas
 var createdUpdatedPlugin = function (schema) {
     schema.add({
         updated: { description: "When this document was last updated", index: true, type: Date },
@@ -268,6 +274,7 @@ exports.findExactlyOne = findExactlyOne;
  * match the conditions to prevent ambiguous updates.
  * @param schema Mongoose Schema
  */
+// biome-ignore lint/suspicious/noExplicitAny: Schema generics with unknown collide with mongoose's loose this-binding on schema.statics
 var upsertPlugin = function (schema) {
     schema.statics.upsert = function (conditions, update) {
         return __awaiter(this, void 0, void 0, function () {
@@ -285,14 +292,16 @@ var upsertPlugin = function (schema) {
                             });
                         }
                         doc = docs[0];
-                        if (doc) {
-                            // If the document exists, update it with the provided update values.
-                            Object.assign(doc, update);
-                            return [2 /*return*/, doc.save()];
-                        }
+                        if (!doc) return [3 /*break*/, 3];
+                        // If the document exists, update it with the provided update values.
+                        Object.assign(doc, update);
+                        return [4 /*yield*/, doc.save()];
+                    case 2: return [2 /*return*/, (_a.sent())];
+                    case 3:
                         combinedData = __assign(__assign({}, conditions), update);
                         newDoc = new this(combinedData);
-                        return [2 /*return*/, newDoc.save()];
+                        return [4 /*yield*/, newDoc.save()];
+                    case 4: return [2 /*return*/, (_a.sent())];
                 }
             });
         });
@@ -313,7 +322,7 @@ var DateOnly = /** @class */ (function (_super) {
     // When using $gt, $gte, $lt, $lte, etc, we need to cast the value to a Date
     DateOnly.prototype.castForQuery = function ($conditional, val, context) {
         if ($conditional == null) {
-            // noExplicitAny: applySetters is an internal Mongoose SchemaType method not in public type definitions
+            // biome-ignore lint/suspicious/noExplicitAny: applySetters is an internal Mongoose SchemaType method not in public type definitions
             return this.applySetters(val, context);
         }
         var handler = this.$conditionalHandlers[$conditional];
@@ -354,5 +363,5 @@ var DateOnly = /** @class */ (function (_super) {
 }(mongoose_1.SchemaType));
 exports.DateOnly = DateOnly;
 // Register DateOnly with Mongoose's Schema.Types
-// noExplicitAny: DateOnly is a custom SchemaType not declared in Mongoose's Schema.Types interface
+// biome-ignore lint/suspicious/noExplicitAny: DateOnly is a custom SchemaType not declared in Mongoose's Schema.Types interface
 mongoose_1.default.Schema.Types.DateOnly = DateOnly;

package/dist/plugins.test.js

@@ -55,6 +55,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var mongoose_1 = require("mongoose");
 var supertest_1 = __importDefault(require("supertest"));
@@ -77,7 +78,6 @@ var StuffModel = (0, mongoose_1.model)("Stuff", stuffSchema);
 (0, bun_test_1.describe)("baseUserPlugin", function () {
     (0, bun_test_1.it)("adds admin and email fields to the schema", function () {
         var testSchema = new mongoose_1.Schema({});
-        // biome-ignore lint/suspicious/noExplicitAny: test schema
         (0, plugins_1.baseUserPlugin)(testSchema);
         var adminPath = testSchema.path("admin");
         (0, bun_test_1.expect)(adminPath).toBeDefined();

package/dist/populate.d.ts

@@ -1,15 +1,22 @@
-import type { Document } from "mongoose";
-export type PopulatePath = {
+import type { Document, Schema } from "mongoose";
+interface OpenApiSchemaNode {
+    description?: string;
+    items?: OpenApiSchemaNode;
+    properties?: Record<string, OpenApiSchemaNode>;
+    type?: string;
+}
+export interface PopulatePath {
     path: string;
-    openApiComponent?: any;
+    openApiComponent?: string;
     fields?: string[];
-};
-export declare const fixMixedFields: (schema: any, properties: Record<string, any>) => void;
-export declare function getOpenApiSpecForModel(model: any, { populatePaths, extraModelProperties, }?: {
+}
+export declare const fixMixedFields: (schema: Schema | null, properties: Record<string, OpenApiSchemaNode> | Record<string, unknown> | null) => void;
+export declare const getOpenApiSpecForModel: (model: any, { populatePaths, extraModelProperties, }?: {
     populatePaths?: PopulatePath[];
     extraModelProperties?: Record<string, unknown>;
-}): {
+}) => {
     properties: Record<string, unknown>;
     required: string[];
 };
-export declare function unpopulate<T>(doc: Document<T>, path: string): Document<T>;
+export declare const unpopulate: <T>(doc: Document<T>, path: string) => Document<T>;
+export {};

package/dist/populate.js

@@ -50,19 +50,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fixMixedFields = void 0;
-exports.getOpenApiSpecForModel = getOpenApiSpecForModel;
-exports.unpopulate = unpopulate;
+exports.unpopulate = exports.getOpenApiSpecForModel = exports.fixMixedFields = void 0;
 var isArray_1 = __importDefault(require("lodash/isArray"));
 var mongoose_to_swagger_1 = __importDefault(require("mongoose-to-swagger"));
 var errors_1 = require("./errors");
 var m2sOptions = {
     props: ["readOnly", "required", "enum", "default"],
 };
-// This function filters an object to only include specified keys.
-// It supports nested keys using dot notation (e.g., 'user.name').
-// If no keys are provided, it returns the original object.
-// The function recursively traverses the object structure to handle nested properties.
+// Keeps only the specified dot-notation keys from an object.
 var filterKeys = function (obj, keysToKeep) {
     if (!keysToKeep) {
         return obj;
@@ -98,7 +93,7 @@ var filterKeys = function (obj, keysToKeep) {
 };
 // Helper function to get the path in the OpenAPI schema, so we can swap out the type for the
 // populated model component or generated type.
-function getPathInSchema(schema, path) {
+var getPathInSchema = function (schema, path) {
     var _a;
     var keys = path.split(".");
     var currentSchema = schema;
@@ -119,23 +114,21 @@ function getPathInSchema(schema, path) {
             break;
         }
         else {
-            throw new Error("Path ".concat(path, " not found in schema at key ").concat(key));
+            throw new errors_1.APIError({ status: 500, title: "Path ".concat(path, " not found in schema at key ").concat(key) });
         }
     }
     return fullPath;
-}
-// Replaces populated properties with the populated schema.
-// Recursively walks a Mongoose schema and fixes any Mixed fields in the
-// OpenAPI properties so they use an empty schema (accepts any type) instead
-// of the `{type: "object", properties: {}}` that mongoose-to-swagger emits.
+};
+// Corrects Mixed-type fields in OpenAPI properties so they accept any value.
 var fixMixedFields = function (schema, properties) {
     var e_1, _a;
     var _b, _c, _d;
     if (!properties || !schema) {
         return;
     }
+    var props = properties;
     try {
-        for (var _e = __values(Object.keys(properties)), _f = _e.next(); !_f.done; _f = _e.next()) {
+        for (var _e = __values(Object.keys(props)), _f = _e.next(); !_f.done; _f = _e.next()) {
             var key = _f.value;
             var schemaPath = schema.path(key);
             if (!schemaPath) {
@@ -143,14 +136,15 @@ var fixMixedFields = function (schema, properties) {
             }
             // Direct Mixed field
             if (schemaPath.instance === "Mixed") {
-                properties[key] = { description: (_b = properties[key]) === null || _b === void 0 ? void 0 : _b.description };
+                props[key] = { description: (_b = props[key]) === null || _b === void 0 ? void 0 : _b.description };
                 continue;
             }
             // Array of sub-documents — check each sub-field for Mixed
-            if (schemaPath.instance === "Array" &&
-                schemaPath.schema &&
-                ((_d = (_c = properties[key]) === null || _c === void 0 ? void 0 : _c.items) === null || _d === void 0 ? void 0 : _d.properties)) {
-                (0, exports.fixMixedFields)(schemaPath.schema, properties[key].items.properties);
+            if (schemaPath.instance === "Array" && schemaPath.schema) {
+                var itemProperties = (_d = (_c = props[key]) === null || _c === void 0 ? void 0 : _c.items) === null || _d === void 0 ? void 0 : _d.properties;
+                if (itemProperties) {
+                    (0, exports.fixMixedFields)(schemaPath.schema, itemProperties);
+                }
             }
         }
     }
@@ -163,7 +157,9 @@ var fixMixedFields = function (schema, properties) {
     }
 };
 exports.fixMixedFields = fixMixedFields;
-function getOpenApiSpecForModel(model, _a) {
+var getOpenApiSpecForModel = function (
+// biome-ignore lint/suspicious/noExplicitAny: noExplicitAny: Mongoose Model param uses deep internal APIs (schema.path().options.ref, schema.virtuals, schema.childSchemas, db.model) that are not exposed in public type definitions
+model, _a) {
     var e_2, _b, _c, e_3, _d, e_4, _e, e_5, _f;
     var _g, _h, _j, _k;
     var _l = _a === void 0 ? {} : _a, populatePaths = _l.populatePaths, extraModelProperties = _l.extraModelProperties;
@@ -296,17 +292,19 @@ function getOpenApiSpecForModel(model, _a) {
         properties: __assign(__assign({}, modelSwagger.properties), extraModelProperties),
         required: (_k = modelSwagger.required) !== null && _k !== void 0 ? _k : [],
     };
-}
+};
+exports.getOpenApiSpecForModel = getOpenApiSpecForModel;
 // Helper function to unpopulate a document that has been populated.
 // This is helpful for supporting backwards compatibility. E.g. you use populatePaths
 // to populate a document but if the version header for the request is below the version
 // that the populatePath was added, we remove the population and just return the _id.
-function unpopulate(doc, path) {
+var unpopulate = function (doc, path) {
     if (!path) {
         throw new errors_1.APIError({ status: 500, title: "path is required for unpopulate" });
     }
     var pathParts = path.split(".");
     // Recursive because we need to support nested paths.
+    // biome-ignore lint/suspicious/noExplicitAny: noExplicitAny: recursive document traversal uses bracket-notation indexing on arbitrary nested document shapes that Mongoose Document types do not expose
     var recursiveUnpopulate = function (current, parts) {
         var e_6, _a;
         var _b;
@@ -352,4 +350,5 @@ function unpopulate(doc, path) {
         return current;
     };
     return recursiveUnpopulate(doc, pathParts);
-}
+};
+exports.unpopulate = unpopulate;

package/dist/populate.test.js

@@ -85,6 +85,7 @@ var __read = (this && this.__read) || function (o, n) {
     return ar;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var mongoose_1 = __importStar(require("mongoose"));
 var populate_1 = require("./populate");

package/dist/realtime/changeStreamWatcher.d.ts

@@ -0,0 +1,73 @@
+import mongoose from "mongoose";
+import type { Server } from "socket.io";
+type ChangeStreamDocument = mongoose.mongo.ChangeStreamDocument;
+import type { User } from "../auth";
+import { type RealtimeRegistryEntry } from "./registry";
+import type { ChangeStreamConfig, RealtimeEvent } from "./types";
+/**
+ * Map MongoDB change stream operation types to our method names.
+ *
+ * Soft deletes (an `update` that sets `deleted: true`) are reclassified as
+ * `"delete"` only when the model has `"delete"` enabled in its realtime
+ * methods. Otherwise they fall back to `"update"` so models that subscribe
+ * to updates (but not deletes) still see the change — without this fallback,
+ * a model configured with `methods: ["create", "update"]` would silently
+ * drop soft-delete events.
+ *
+ * Exported for testing.
+ */
+export declare const mapOperationType: (operationType: string, change: ChangeStreamDocument, enabledMethods?: ReadonlyArray<"create" | "update" | "delete">) => "create" | "update" | "delete" | null;
+/**
+ * Determine which Socket.io rooms to emit to based on the room strategy.
+ * Exported for testing.
+ */
+export declare const resolveRooms: (entry: RealtimeRegistryEntry, doc: any, method: string) => string[];
+/**
+ * Ensure serialized documents include `id` to match REST API responses.
+ * Change stream fullDocument payloads are raw BSON objects with `_id` only.
+ */
+export declare const ensureApiId: (data: unknown) => unknown;
+/**
+ * Serialize a document for emission.
+ *
+ * Precedence:
+ *   1. `realtimeResponseHandler` if provided (full control over what's emitted).
+ *   2. modelRouter `responseHandler` if provided — invoked with a synthetic request
+ *      so the same stripping logic used for REST responses (e.g. removing `hash`/`salt`)
+ *      applies to realtime events. This prevents accidental leaks when an app only
+ *      configures sanitization in the REST `responseHandler`.
+ *   3. `toJSON()` fallback.
+ *
+ * If a user-supplied handler throws, we re-throw so the caller's outer try/catch
+ * records the failure and the event is dropped. Falling back to `toJSON()` here
+ * would risk leaking unsanitized fields (e.g. `hash`/`salt`) that the handler
+ * was supposed to strip.
+ */
+export declare const serializeDoc: (entry: RealtimeRegistryEntry, doc: any, method: "create" | "update" | "delete", user?: User) => Promise<any>;
+export declare const emitToAuthorizedRoom: (io: Server, room: string, event: RealtimeEvent, entry: RealtimeRegistryEntry, fullDocument: any, logDebug: (msg: string) => void) => Promise<void>;
+/**
+ * Emit a sync event to document-specific and query rooms.
+ *
+ * Document rooms: `document:{collection}:{docId}` — clients subscribed to a single document.
+ * Query rooms: `query:{queryId}` — clients subscribed to a query filter. The change stream
+ * watcher evaluates whether the document matches each active query for the collection.
+ *
+ * For deletes, we are careful not to leak cross-user activity:
+ *   - Soft deletes (fullDocument present) are matched against each query like updates so
+ *     query subscribers only see deletes for docs that matched their filter.
+ *   - Hard deletes (fullDocument absent) on owner-strategy collections are NOT forwarded
+ *     to query rooms — subscribers will reconcile on their next fetch. Other strategies
+ *     forward the delete because the model/broadcast rooms are not user-scoped.
+ *
+ * Exported for testing.
+ */
+export declare const emitToDocumentAndQueryRooms: (io: Server, collection: string, event: RealtimeEvent, fullDocument: any, logDebug: (msg: string) => void, entry?: RealtimeRegistryEntry) => Promise<void>;
+/**
+ * Start watching MongoDB change streams and emitting real-time events.
+ */
+export declare const startChangeStreamWatcher: (io: Server, config?: ChangeStreamConfig, debug?: boolean) => void;
+/**
+ * Stop the change stream watcher.
+ */
+export declare const stopChangeStreamWatcher: () => Promise<void>;
+export {};