@terreno/api 0.18.0 → 0.20.0

package/src/configurationPlugin.ts

@@ -11,6 +11,12 @@ export interface SecretFieldMeta {
   path: string;
   secretProvider?: string;
   secretName: string;
+  /**
+   * Optional secret version to pin resolution to. When omitted the provider
+   * resolves the latest version. Discovered from the `secretVersion` schema
+   * path option.
+   */
+  version?: string;
 }
 
 /**
@@ -18,7 +24,15 @@ export interface SecretFieldMeta {
  */
 export interface SecretProvider {
   name: string;
-  getSecret(secretName: string): Promise<string | null>;
+  /**
+   * Resolve a secret value by name. Returns `null` when the secret is not found.
+   *
+   * @param secretName - The secret identifier (short name or provider-specific path).
+   * @param version - Optional version to pin resolution to. Providers that do not
+   *   support versioning (e.g. environment variables) ignore this parameter. When
+   *   omitted, the latest version is resolved.
+   */
+  getSecret(secretName: string, version?: string): Promise<string | null>;
 }
 
 /**
@@ -30,6 +44,18 @@ export interface ConfigurationPluginOptions {
    * Typically set during app startup so the model can resolve secrets on demand.
    */
   secretProvider?: SecretProvider;
+  /**
+   * When `true`, adds a `_singleton` sentinel field with a unique index to
+   * enforce the singleton constraint at the database level.
+   *
+   * Defaults to `false`. Leave this off when the consuming app already enforces
+   * a single non-deleted document via the pre-save guard (the default behavior)
+   * or via its own indexes/soft-delete plugin, to avoid double-enforcement and
+   * conflicting indexes.
+   *
+   * @defaultValue false
+   */
+  enforceSingletonIndex?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -75,14 +101,26 @@ export interface ConfigurationStatics<T extends object> {
   getConfig(): Promise<T & Document>;
   /** Get a specific value by dot-notation key. */
   getConfig<P extends Paths<T>>(key: P): Promise<PathValue<T, P>>;
-  /** Update the singleton configuration document (deep merge). */
+  /**
+   * Update the singleton configuration document.
+   *
+   * The patch is flattened into MongoDB dotted paths and applied with
+   * `findOneAndUpdate({$set})`. This preserves sibling fields inside nested
+   * subdocuments when a partial nested patch is supplied, and tolerates legacy /
+   * out-of-schema fields already persisted on the document (unlike a full
+   * `doc.save()`, which throws under `strict: "throw"`).
+   */
   updateConfig(updates: DeepPartial<T>): Promise<T & Document>;
   /** Get secret field metadata discovered from the schema. */
   getSecretFields(): SecretFieldMeta[];
   /**
    * Resolve all secret field values from a provider.
    * Uses the provider passed here, or falls back to the one configured in the plugin options.
-   * Returns a map of path -> value.
+   * Returns an **in-memory** map of path -> value for programmatic use (startup
+   * self-checks, request-time resolution).
+   *
+   * This method never persists resolved values. Secret material must never be
+   * written to the configuration document.
    */
   resolveSecrets(provider?: SecretProvider): Promise<Map<string, string>>;
 }
@@ -103,6 +141,47 @@ export interface ConfigurationStatics<T extends object> {
  */
 export interface ConfigurationModel<T extends object> extends Model<T>, ConfigurationStatics<T> {}
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Flattens a nested patch into MongoDB-style dotted paths, recursing into plain
+ * objects only; arrays and other values are treated as leaves.
+ *
+ * @example
+ * flattenToDotPaths({a: {b: 1}}) // => [["a.b", 1]]
+ */
+export const flattenToDotPaths = (
+  obj: Record<string, unknown>,
+  prefix = ""
+): Array<[string, unknown]> => {
+  const out: Array<[string, unknown]> = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const isPlainObject =
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      Object.getPrototypeOf(value) === Object.prototype;
+    if (isPlainObject) {
+      out.push(...flattenToDotPaths(value as Record<string, unknown>, path));
+    } else {
+      out.push([path, value]);
+    }
+  }
+  return out;
+};
+
+/**
+ * Builds the filter used to locate the singleton document. When the schema is
+ * soft-delete aware (has a `deleted` path, e.g. via `isDeletedPlugin`), the
+ * singleton is "the one non-deleted document"; otherwise any document matches.
+ */
+const buildSingletonFilter = (schema: Schema): Record<string, unknown> => {
+  return schema.path("deleted") ? {deleted: false} : {};
+};
+
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
@@ -111,13 +190,23 @@ export interface ConfigurationModel<T extends object> extends Model<T>, Configur
  * Mongoose schema plugin that adds singleton configuration behavior.
  *
  * Adds:
- * - Pre-save hook enforcing exactly one document
+ * - Pre-save hook enforcing exactly one non-deleted document (soft-delete aware
+ *   when the schema has a `deleted` path, e.g. via `isDeletedPlugin`)
  * - `getConfig()` static: fetches or creates the singleton (full doc or keyed value)
- * - `updateConfig(updates)` static: patches the singleton
+ * - `updateConfig(updates)` static: patches the singleton via `findOneAndUpdate({$set})`
+ *   with dotted paths (preserves sibling subdoc fields; tolerates legacy fields)
  * - `getSecretFields()` static: returns metadata for fields with `secret: true`
- * - `resolveSecrets(provider?)` static: fetches secret values, using the plugin provider by default
+ * - `resolveSecrets(provider?)` static: resolves secret values into an in-memory map,
+ *   using the plugin provider by default (never persists values)
+ * - Hard-delete blockers (`deleteOne`/`deleteMany`/`findOneAndDelete`); soft deletes
+ *   (setting `deleted: true`) are allowed
+ *
+ * Soft deletes are allowed and a soft-deleted document does not block creating a
+ * new singleton. The `_singleton` unique index is opt-in via
+ * `enforceSingletonIndex` (default off).
  *
- * Mark fields as secrets using schema path options:
+ * Mark fields as secrets using schema path options. Pin a version with the
+ * optional `secretVersion` option:
  * ```typescript
  * const configSchema = new Schema({
  *   apiKey: {
@@ -125,6 +214,7 @@ export interface ConfigurationModel<T extends object> extends Model<T>, Configur
  *     description: "Third-party API key",
  *     secret: true,
  *     secretName: "my-api-key",
+ *     secretVersion: "3", // optional — resolves "latest" when omitted
  *   },
  * });
  * configSchema.plugin(configurationPlugin, {secretProvider: new EnvSecretProvider()});
@@ -136,24 +226,31 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
   // Apply findOneOrNone so the singleton lookup avoids bare Model.findOne (idempotent).
   findOneOrNone(schema);
 
-  // Add a sentinel field with a unique index to enforce singleton at the DB level.
-  // All config documents get _singleton: "config", and the unique index prevents duplicates.
-  schema.add({
-    _singleton: {
-      default: "config",
-      description: "Sentinel field enforcing singleton constraint",
-      immutable: true,
-      select: false,
-      type: String,
-    },
-  });
-  schema.index({_singleton: 1}, {unique: true});
+  // Optionally add a sentinel field with a unique index to enforce the singleton
+  // at the database level. This is opt-in (default off) so it does not conflict
+  // with consumers that already enforce a single non-deleted document via the
+  // pre-save guard below or via their own soft-delete plugin/indexes.
+  if (pluginOptions.enforceSingletonIndex) {
+    schema.add({
+      _singleton: {
+        default: "config",
+        description: "Sentinel field enforcing singleton constraint",
+        immutable: true,
+        select: false,
+        type: String,
+      },
+    });
+    schema.index({_singleton: 1}, {unique: true});
+  }
 
-  // Enforce singleton: only one document allowed (application-level guard)
+  // Enforce singleton: only one non-deleted document allowed (application-level
+  // guard). Soft-delete-aware: a soft-deleted document does not block creating a
+  // new singleton.
   schema.pre("save", async function () {
     if (this.isNew) {
+      const filter = buildSingletonFilter(schema);
       // Cheap existence check — no document needs to be returned.
-      const existing = await (this.constructor as Model<unknown>).exists({});
+      const existing = await (this.constructor as Model<unknown>).exists(filter);
       if (existing) {
         throw new APIError({
           status: 409,
@@ -183,9 +280,10 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
 
   // Static: get the singleton configuration document or a value at a path (race-safe via upsert)
   schema.statics.getConfig = async function (key?: string): Promise<unknown> {
+    const singletonFilter = buildSingletonFilter(this.schema);
     const findSingleton = (): Promise<Document | null> =>
       (this as unknown as FindOneOrNonePlugin<unknown>).findOneOrNone(
-        {}
+        singletonFilter
       ) as Promise<Document | null>;
     let config: Document | null = await findSingleton();
     if (!config) {
@@ -222,14 +320,44 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
     return value;
   };
 
-  // Static: update the singleton configuration document (race-safe)
+  // Static: update the singleton configuration document via $set dotted paths.
+  // Flattening to dotted paths preserves sibling subdoc fields and tolerates
+  // legacy/out-of-schema fields already persisted on the document.
   schema.statics.updateConfig = async function (
     updates: Record<string, unknown>
   ): Promise<unknown> {
-    const config = await (this as ConfigurationModel<Record<string, unknown>>).getConfig();
-    Object.assign(config, updates);
-    await (config as Document).save();
-    return config;
+    const singletonFilter = buildSingletonFilter(this.schema);
+    const setFields: Record<string, unknown> = {};
+    for (const [path, value] of flattenToDotPaths(updates)) {
+      setFields[path] = value;
+    }
+
+    // Nothing to set — return the current singleton (creating it if missing).
+    if (Object.keys(setFields).length === 0) {
+      return (this as unknown as ConfigurationModel<Record<string, unknown>>).getConfig();
+    }
+
+    // runValidators keeps schema validation (enum/min/custom validators) on the
+    // patched paths, matching the prior doc.save() behavior. Legacy/out-of-schema
+    // fields already on the document are untouched (not in $set), so they are not
+    // re-validated.
+    const updated = await this.findOneAndUpdate(
+      singletonFilter,
+      {$set: setFields},
+      {new: true, runValidators: true}
+    );
+    if (updated) {
+      return updated;
+    }
+
+    // No singleton yet — create one (with subdocument defaults applied), then
+    // apply the patch.
+    await (this as unknown as ConfigurationModel<Record<string, unknown>>).getConfig();
+    return this.findOneAndUpdate(
+      singletonFilter,
+      {$set: setFields},
+      {new: true, runValidators: true}
+    ).orFail();
   };
 
   // Static: discover secret fields from schema options
@@ -243,6 +371,7 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
             path: prefix ? `${prefix}.${pathName}` : pathName,
             secretName: (opts.secretName as string) ?? pathName,
             secretProvider: opts.secretProvider as string | undefined,
+            version: opts.secretVersion as string | undefined,
           });
         }
         // Recurse into subschemas
@@ -275,7 +404,7 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
 
     const results = await Promise.allSettled(
       secrets.map(async (meta: SecretFieldMeta) => {
-        const value = await resolvedProvider.getSecret(meta.secretName);
+        const value = await resolvedProvider.getSecret(meta.secretName, meta.version);
         if (value !== null) {
           resolved.set(meta.path, value);
         }

package/src/expressServer.test.ts

@@ -812,7 +812,6 @@ describe("expressServer", () => {
       // Mock app.listen on the Express prototype to avoid opening a real port
       const express = await import("express");
       const originalListen = express.default.application.listen;
-      // biome-ignore lint/suspicious/noExplicitAny: mocking Express internals requires type escape
       express.default.application.listen = mock(function (this: unknown, ...args: unknown[]) {
         const cb = args.find((a: unknown) => typeof a === "function") as (() => void) | undefined;
         if (cb) {

package/src/openApi.ts

@@ -8,7 +8,7 @@ import type {ModelRouterOptions, OpenApiMiddleware} from "./api";
 import {logger} from "./logger";
 import {getOpenApiSpecForModel} from "./populate";
 
-const noop = (_a, _b, next) => next();
+const noop = (_a: unknown, _b: unknown, next: () => void) => next();
 
 const m2sOptions = {
   props: ["readOnly", "required", "enum", "default"],
@@ -44,7 +44,7 @@ export const defaultOpenApiErrorResponses = {
 };
 
 // We repeat this constantly, so we make it a component so we only have to define it once.
-function createAPIErrorComponent(openApi?: OpenApiMiddleware) {
+const createAPIErrorComponent = (openApi?: OpenApiMiddleware): void => {
   // Create a schema component called APIError
   openApi?.component("schemas", "APIError", {
     properties: {
@@ -111,12 +111,12 @@ function createAPIErrorComponent(openApi?: OpenApiMiddleware) {
     },
     type: "object",
   });
-}
+};
 
-export function getOpenApiMiddleware<T>(
+export const getOpenApiMiddleware = <T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-): express.RequestHandler {
+): express.RequestHandler => {
   createAPIErrorComponent(options.openApi);
   if (!options.openApi?.path) {
     // Just log this once rather than for each middleware.
@@ -158,12 +158,12 @@ export function getOpenApiMiddleware<T>(
       options.openApiOverwrite?.get ?? {}
     )
   );
-}
+};
 
-export function listOpenApiMiddleware<T>(
+export const listOpenApiMiddleware = <T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-): express.RequestHandler {
+): express.RequestHandler => {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -324,12 +324,12 @@ export function listOpenApiMiddleware<T>(
       options.openApiOverwrite?.list ?? {}
     )
   );
-}
+};
 
-export function createOpenApiMiddleware<T>(
+export const createOpenApiMiddleware = <T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-): express.RequestHandler {
+): express.RequestHandler => {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -376,12 +376,12 @@ export function createOpenApiMiddleware<T>(
       options.openApiOverwrite?.create ?? {}
     )
   );
-}
+};
 
-export function patchOpenApiMiddleware<T>(
+export const patchOpenApiMiddleware = <T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-): express.RequestHandler {
+): express.RequestHandler => {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -428,12 +428,12 @@ export function patchOpenApiMiddleware<T>(
       options.openApiOverwrite?.update ?? {}
     )
   );
-}
+};
 
-export function deleteOpenApiMiddleware<T>(
+export const deleteOpenApiMiddleware = <T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-): express.RequestHandler {
+): express.RequestHandler => {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -456,16 +456,16 @@ export function deleteOpenApiMiddleware<T>(
       options.openApiOverwrite?.delete ?? {}
     )
   );
-}
+};
 
 // This is a generic OpenAPI wrapper for a read that returns any object described by `properties`.
 // Useful for endpoints that don't directly map to a model.
-export function readOpenApiMiddleware<T>(
+export const readOpenApiMiddleware = <T>(
   options: Partial<ModelRouterOptions<T>>,
   properties: Record<string, unknown>,
   required: string[],
   queryParameters: Array<Record<string, unknown>>
-): express.RequestHandler {
+): express.RequestHandler => {
   if (!options.openApi?.path) {
     // Just log this once rather than for each middleware.
     logger.debug(
@@ -502,4 +502,4 @@ export function readOpenApiMiddleware<T>(
       options.openApiOverwrite?.get ?? {}
     )
   );
-}
+};

package/src/populate.test.ts

@@ -265,6 +265,31 @@ describe("getOpenApiSpecForModel edge cases", () => {
   });
 });
 
+describe("getOpenApiSpecForModel populate with existing properties", () => {
+  it("merges populated properties into a path that already has properties", () => {
+    const result = getOpenApiSpecForModel(FoodModel, {
+      populatePaths: [{path: "likesIds.userId"}],
+    });
+    // likesIds is an array subschema with its own properties already;
+    // populating userId should merge the user properties into the existing structure.
+    expect(result.properties.likesIds).toBeDefined();
+    const likesIds = result.properties.likesIds as Record<string, unknown>;
+    const items = likesIds.items as Record<string, Record<string, unknown>>;
+    expect(items.properties.userId).toBeDefined();
+  });
+
+  it("creates intermediate path structure when navigating to nested populate", () => {
+    // eatenBy is defined as [{ ref: "User", type: ObjectId }] - an array of refs.
+    // When we populate eatenBy, the openApiPath resolves through items.
+    const result = getOpenApiSpecForModel(FoodModel, {
+      populatePaths: [{path: "eatenBy"}],
+    });
+    expect(result.properties.eatenBy).toBeDefined();
+    const eatenBy = result.properties.eatenBy as Record<string, unknown>;
+    expect(eatenBy.items).toBeDefined();
+  });
+});
+
 describe("filterKeys (via getOpenApiSpecForModel populatePaths)", () => {
   it("filters populated fields using dot-notation keys", () => {
     const result = getOpenApiSpecForModel(FoodModel, {

package/src/realtime/queryMatcher.ts

@@ -6,7 +6,6 @@
  * Supports: equality, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, $or, $not.
  */
 
-// biome-ignore lint/suspicious/noExplicitAny: traversing arbitrary nested document fields by user-supplied dotted path
 const getNestedValue = (doc: any, path: string): any => {
   const parts = path.split(".");
   let current = doc;
@@ -19,7 +18,6 @@ const getNestedValue = (doc: any, path: string): any => {
   return current;
 };
 
-// biome-ignore lint/suspicious/noExplicitAny: value may be any document field type (string, number, ObjectId, etc.)
 const normalize = (value: any): any => {
   if (value === null || value === undefined) {
     return value;
@@ -36,7 +34,6 @@ const normalize = (value: any): any => {
   return value;
 };
 
-// biome-ignore lint/suspicious/noExplicitAny: rawValue is an arbitrary document field, condition is an arbitrary user query operand
 const matchesCondition = (rawValue: any, condition: any): boolean => {
   const value = normalize(rawValue);
 
@@ -91,7 +88,6 @@ const matchesCondition = (rawValue: any, condition: any): boolean => {
           return false;
         }
         const inValues = operand.map(normalize);
-        // biome-ignore lint/suspicious/noExplicitAny: normalized value of arbitrary document field
         if (!inValues.some((v: any) => v === value || String(v) === String(value))) {
           return false;
         }
@@ -102,7 +98,6 @@ const matchesCondition = (rawValue: any, condition: any): boolean => {
           return false;
         }
         const ninValues = operand.map(normalize);
-        // biome-ignore lint/suspicious/noExplicitAny: normalized value of arbitrary document field
         if (ninValues.some((v: any) => v === value || String(v) === String(value))) {
           return false;
         }
@@ -137,7 +132,6 @@ const matchesCondition = (rawValue: any, condition: any): boolean => {
  * @param query - MongoDB-style query object
  * @returns true if the document matches all query conditions
  */
-// biome-ignore lint/suspicious/noExplicitAny: doc is arbitrary; query values are arbitrary user-supplied JSON
 export const matchesQuery = (doc: any, query: Record<string, any>): boolean => {
   for (const [key, condition] of Object.entries(query)) {
     if (key === "$and") {

package/src/realtime/queryStore.ts

@@ -9,7 +9,6 @@
 
 interface QuerySubscription {
   collection: string;
-  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
   query: Record<string, any>;
   queryId: string;
 }
@@ -18,13 +17,8 @@ interface QuerySubscription {
  * Compute a deterministic queryId from collection and query on the server side.
  * This prevents clients from hijacking other subscriptions by providing a colliding queryId.
  */
-export const computeQueryId = (
-  collection: string,
-  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
-  query: Record<string, any>
-): string => {
+export const computeQueryId = (collection: string, query: Record<string, any>): string => {
   const sortedKeys = Object.keys(query).sort();
-  // biome-ignore lint/suspicious/noExplicitAny: mirrors the input query value shape
   const normalized: Record<string, any> = {};
   for (const key of sortedKeys) {
     normalized[key] = query[key];
@@ -45,7 +39,6 @@ const socketQueries = new Map<string, Set<string>>();
 export const addQuerySubscription = (
   socketId: string,
   collection: string,
-  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
   query: Record<string, any>,
   queryId: string
 ): void => {
@@ -109,9 +102,7 @@ export const removeAllSocketQueries = (socketId: string): void => {
  */
 export const getQuerySubscriptionsForCollection = (
   collection: string
-  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
 ): {queryId: string; query: Record<string, any>}[] => {
-  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
   const result: {queryId: string; query: Record<string, any>}[] = [];
 
   for (const [queryId, sub] of querySubscriptions) {