@web-ts-toolkit/moo 0.43.0 → 0.48.0

package/README.md

@@ -10,8 +10,8 @@ pnpm add mongoose @web-ts-toolkit/moo
 
 Peer dependencies:
 
-- `mongoose >= 8`
-- `@egose/keycloak-fluent ^0.7` only when using `@web-ts-toolkit/moo/plugins/keycloak-user-sync`
+- `mongoose >= 8` (tested with Mongoose 8.24.x and 9.x)
+- `@egose/keycloak-fluent >=0.12.1 <0.15.0` only when using `@web-ts-toolkit/moo/plugins/keycloak-user-sync` (tested floor `0.12.1`, current `0.14.x`)
 
 ## Highlights
 
@@ -46,7 +46,7 @@ Subpath entrypoints:
 
 - `@web-ts-toolkit/moo/schema` — schema field helpers
 - `@web-ts-toolkit/moo/is` — type guards such as `isObjectId(...)`
-- `@web-ts-toolkit/moo/utils` — mongoose utilities
+- `@web-ts-toolkit/moo/utils` — `isSchema`, `isObjectIdType`, `isReference`, and the `ReferenceShape` type
 - `@web-ts-toolkit/moo/plugins` — plugin entrypoint
 - `@web-ts-toolkit/moo/plugins/cascade-delete` — cascade-delete plugin
 - `@web-ts-toolkit/moo/plugins/model-function` — model-function plugin
@@ -73,6 +73,79 @@ userSchema.plugin(cascadeDeletePlugin, {
 });
 ```
 
+## Model Function Plugin
+
+```ts
+import mongoose, { type Model } from 'mongoose';
+import {
+  type ModelDocument,
+  type ModelFunctionInstanceMethods,
+  type ModelFunctionStaticMethods,
+  modelFunctionPlugin,
+} from '@web-ts-toolkit/moo';
+
+type Cart = {
+  name: string;
+  price: number;
+};
+
+// Keep result types free of the CartDocument alias (plain values, not the
+// document) so the aliases never circularly reference each other.
+type CartMethods = ModelFunctionInstanceMethods<'applyDiscount', [suffix: string, priceChange: number], number> &
+  ModelFunctionInstanceMethods<'applyDiscountAsync', [suffix: string, priceChange: number], Promise<number>>;
+
+type CartDocument = ModelDocument<Cart, CartMethods>;
+
+type CartModel = Model<Cart, Record<string, never>, CartMethods> &
+  ModelFunctionStaticMethods<'applyDiscount', CartDocument, [suffix: string, priceChange: number], number> &
+  ModelFunctionStaticMethods<
+    'applyDiscountAsync',
+    CartDocument,
+    [suffix: string, priceChange: number],
+    Promise<number>
+  >;
+
+const cartSchema = new mongoose.Schema<Cart, CartModel, CartMethods>({
+  name: { type: String, required: true },
+  price: { type: Number, required: true },
+});
+
+// No explicit plugin generics: the method name, argument tuple, and result
+// are inferred from the options. The second type argument is the method
+// *name* (for example `'applyDiscount'`), never the methods object.
+cartSchema.plugin(modelFunctionPlugin, {
+  fnName: 'applyDiscount',
+  fn: (cart: CartDocument, suffix: string, priceChange: number) => {
+    cart.price += priceChange;
+    return cart.price;
+  },
+});
+
+cartSchema.plugin(modelFunctionPlugin, {
+  fnName: 'applyDiscountAsync',
+  fn: async (cart: CartDocument, suffix: string, priceChange: number) => {
+    cart.price += priceChange;
+    return cart.price;
+  },
+});
+
+const Cart = mongoose.model<Cart, CartModel>('Cart', cartSchema);
+
+const cart = await Cart.create({ name: 'laptop', price: 2000 });
+const syncPrice: number = Cart.applyDiscount(cart, 'premium', 100);
+const instancePrice: number = cart.applyDiscount('premium', 100);
+const byId: number | null = await Cart.applyDiscountById(cart._id.toString(), 'premium', 100);
+const asyncById: number | null = await Cart.applyDiscountAsyncById(cart._id, 'premium', 100);
+```
+
+Each registration adds three typed surfaces: an instance method, a static taking the document first, and a `ById` static that loads the document and returns `null` when it is missing. Wrong argument types fail compilation.
+
+## Schema Helpers
+
+`uniqueNullableString(field, overrides?)` returns a partial-unique field definition that allows any number of `null`/missing values while rejecting duplicate strings (including `''`): the partial index only covers string-typed values (`{ [field]: { $type: 'string' } }`). `uniqueEmptiableString(field, overrides?)` additionally ignores empty strings (both `null` and `''` repeat; only duplicate non-empty strings conflict) via `{ [field]: { $type: 'string', $gt: '' } }`. Extra `overrides` are spread over the defaults at runtime and reflected in the inferred return type, so overriding `default`, `trim`, or `index` replaces the fixed default type instead of keeping it.
+
+`isObjectId(value)` is a strict canonical guard: only 24-character lowercase hex strings and `mongoose.Types.ObjectId` instances from this package's `mongoose` copy pass. Uppercase hex, 12-byte strings, structural impostors with matching `toString()`, foreign BSON copies, buffers, and throwing accessors are rejected without invoking arbitrary coercion.
+
 ## New Document Plugin
 
 ```ts
@@ -92,6 +165,20 @@ userSchema.plugin(newDocumentPlugin, {
 
 The plugin runs `fn` after the first successful `save()` of a new document. Later saves of the same document do not run it.
 
+Supported operations: only document `save()` is observed (a `pre('save')` snapshot of `isNew` plus a `post('save')` invocation). Query inserts, `insertMany()` fast paths that skip document middleware, and updates to existing documents never trigger the callback.
+
+Delivery scope: post-save notification, not durable delivery. The callback runs after MongoDB persistence; a throwing callback rejects the post-save hook but cannot roll back the committed write, and there is no outbox, retry, or exactly-once guarantee across transaction retries or reentrant saves. Applications that need transactional delivery should record their own outbox intent inside the MongoDB transaction and process it after commit.
+
+## Cascade Delete Plugin
+
+Relationship mode (`localField` + `foreignField`) is fail-closed: missing/`null`/empty-string local keys and empty reference arrays resolve to zero dependents and delete nothing, so unrelated records with a missing/`null` foreign key survive. A local field omitted by a projection is distinguished from an intentionally empty relation — when the path is provably deselected the lookup throws instead of silently reporting zero dependents. Supplemental `extraForeignFilter` constraints are composed conjunctively (`{ $and: [relationship, extra] }`), so an extra filter on the relationship field (including `$or`/`$and` payloads) can only narrow, never replace or widen, the deletion set. Explicit full-filter mode (`foreignFilter`) is a separate contract: the resolved filter is used as-is and any `extraForeignFilter` is ignored; resolvers returning `null`/`undefined`/non-objects resolve to zero dependents. Empty full filters (`{}`) are rejected by default at registration and at runtime because they would match the whole dependent collection; there is currently no broad-delete opt-in. Invalid `model`/field combinations and non-object static filters throw at `schema.plugin(...)` time.
+
+Deletion always removes fully hydrated dependent documents through their own document `deleteOne()` (never bulk writes), so nested cascades and custom document hooks observe required fields across multi-level custom-`localField` chains. Internal deletion traversal pages dependent `_id`s (`batchSize`, default `100`) and bounds in-flight deletes (`maxConcurrency`, default `8`; forced to `1` inside an active transaction), instead of materializing and deleting the whole set at once. Public `findDependents()` still returns an array. A dependent-hook failure rejects the parent `deleteOne()` after the parent is already removed (fail-fast, remaining batches skipped; abort the transaction to restore everything when in one); already-deleted rows are skipped. Repeated references delete once per level; diamonds/cycles terminate with at-least-once hook delivery.
+
+Supported operations and timing: only document `deleteOne()` is intercepted (`pre`/`post('deleteOne', { document: true, query: false })`). Query deletes (`deleteMany()`, `findOneAndDelete()`, query `deleteOne()`) and query updates bypass the cascade. The `pre('deleteOne')` hook validates the execution context before the parent is removed (cross-client sessions and transactions on standalone topologies reject there); the `post('deleteOne')` hook runs after the parent is already removed, so a later dependent failure rejects the parent promise without restoring the parent outside a transaction. Dependent models resolve through the owning model's connection and the effective session (explicit `deleteOne({ session })` option, else the document-bound `$session()`) flows through dependent reads and deletes including nested cascades. `maxConcurrency` and `batchSize` must be integers `>= 1` when provided and are validated at `schema.plugin(...)` time.
+
+Typed filters accept MongoDB operators per field (`{ price: { $gt: 5 } }`, `{ price: { $in: [...] } }`, plus `$and`/`$or` payloads through the index signature) and are forwarded to Mongoose unchanged. The no-argument `findDependents()`/`findOrphans()` overloads return `Partial` maps: entries whose lookup is unsupported or resolved to nullish are omitted rather than reported as empty arrays. `findOrphans()` support: scalar `_id` relations and `[{ type: ObjectId, ref }]` arrays are supported; non-`_id` local keys with a hardcoded `distinct('_id')`, dotted foreign paths, `{ type: [ObjectId], ref }` syntax, dynamic `refPath`, and `foreignFilter`-only relationships are unsupported and resolve to `null` (omitted from the map) rather than silently succeeding. Null/missing foreign rows are reported as orphans; per-page `$not/$in` batching is not a correct collection-scale anti-join, so a server-side `$lookup` strategy is deferred to a follow-up.
+
 ## Keycloak User Sync
 
 Install the optional Keycloak peer before using this entrypoint:
@@ -120,9 +207,26 @@ const userSchema = new Schema({
   lastName: String,
   archived: Boolean,
   roles: [String],
-  pendingPassword: String,
+  tier: String,
+  tenantId: String,
+  subscription: { plan: String },
+  // No stored pendingPassword path: the pending credential below is a
+  // virtual and is never persisted to MongoDB.
 });
 
+// Genuinely non-persisted pending-password input. Virtuals are not stored in
+// MongoDB; the value lives only in memory until the Keycloak reset-password
+// call. Never add a persisted `pendingPassword` schema path holding
+// plaintext, and clear the virtual after sync.
+userSchema
+  .virtual('pendingPassword') // pragma: allowlist secret
+  .get(function (this: { $locals: Record<string, unknown> }) {
+    return this.$locals.pendingPassword as string | undefined;
+  })
+  .set(function (this: { $locals: Record<string, unknown> }, value: string | undefined) {
+    this.$locals.pendingPassword = value;
+  });
+
 userSchema.plugin(keycloakUserSyncPlugin, {
   client: keycloak,
   realm: 'application',
@@ -144,7 +248,14 @@ userSchema.plugin(keycloakUserSyncPlugin, {
   mapPassword(document) {
     return document.get('pendingPassword') as string | undefined;
   },
+  // Declared mapper dependencies: the mapped schema paths above must exist.
+  // passwordPaths covers the non-persisted virtual backing input.
   attributePaths: ['tenantId', 'subscription.plan'],
+  rolePaths: ['tier'],
+  passwordPaths: ['pendingPassword'],
+  mapRoles(_roles, document) {
+    return document.get('tier') === 'pro' ? ['editor'] : [];
+  },
   mapAttributes(document) {
     return {
       tenantId: document.get('tenantId'),
@@ -170,10 +281,12 @@ The plugin:
 - can update the Keycloak password when `syncFields.password` is explicitly enabled
 - reads `archived` as the inverse of Keycloak `enabled`, falling back to an `enabled` field
 
-Configuration is validated when `schema.plugin(...)` runs. `realm`, configured paths, managed role/attribute names, and attribute trigger paths are trimmed and must be non-empty. `identifyBy` accepts one identity or a non-empty ordered list containing only `providerId`, `username`, and `email`. Built-in synced field paths must exist in the Mongoose schema; mapper-driven `attributePaths` can name dynamic fields that the mapper reads. Register the plugin only once per schema.
+Configuration is validated when `schema.plugin(...)` runs. `realm`, configured paths, managed role/attribute names, and attribute/role/password trigger paths are trimmed and must be non-empty. `identifyBy` accepts one identity or a non-empty ordered list containing only `providerId`, `username`, and `email`. Built-in synced field paths must exist in the Mongoose schema; mapper-driven `attributePaths`/`rolePaths`/`passwordPaths` name the additional Mongoose paths the mapper reads (as in the example above, where `tenantId`, `subscription.plan`, `tier`, and the `pendingPassword` virtual are all declared). Register the plugin only once per schema.
 
 The plugin snapshots its options at registration, so later mutation of the caller's options object does not change sync behavior. `providerId` is server-controlled after persistence: applications may set it while creating a new document to link an existing Keycloak user, but changing it later is rejected before any remote call so ordinary document updates cannot redirect synchronization to another Keycloak account.
 
+Saves and deletes share one persisted-identity boundary. New local documents perform explicitly authorized initial linking through their current identity values. Existing documents resolve only through their persisted snapshot: a stored `providerId` is authoritative, and a changed username or email that resolves to a different remote user fails closed instead of relinking — the conflicting update, credential reset, role change, or delete is never sent to that other account. A stale persisted `providerId`, a missing persisted local row, or a delete of a never-persisted document is likewise rejected before any destructive remote call. These identity rejections apply independently of `throwOnError`: with `throwOnError: false` a conflicting save still succeeds locally while leaving the other account untouched, and a conflicting delete always blocks local deletion so the verified binding remains retryable. Migration implication: after adopting this contract, rows whose stored `providerId` no longer exists remotely fail closed on sync; clear or re-link the stored binding explicitly rather than changing a profile field and expecting a silent relink.
+
 When the realm allows duplicate emails, the plugin always prioritizes configured `providerId` and `username` identities before email. An email lookup proceeds only when it has exactly one match; multiple matches are reported as an error, and no user is changed or deleted.
 
 Use `paths` to map different Mongoose path names. Use `syncFields` to disable profile fields, role syncing, or attribute syncing. Use `mapRoles` to translate application roles. Role sync is additive-only by default: desired local roles are assigned, but unrelated existing Keycloak realm roles are preserved. Set `managedRoles` to the exact role names this plugin owns; only those roles may be removed when omitted from an explicit local roles array. An absent or non-array roles value is treated as no role-sync intent. An empty array intentionally removes currently assigned managed roles while preserving unmanaged roles. `ensureRoles` defaults to `true`, so desired missing roles are created before assignment; set it to `false` if typos or insufficient administrative privileges should fail instead of creating roles. `maxRolesPerSync` defaults to `100` and rejects larger desired role arrays before role lookup or mapping requests, bounding caller-controlled remote work.
@@ -184,9 +297,11 @@ For existing Keycloak users, owned string profile fields (`username`, `email`, `
 
 Attributes are normalized to Keycloak string arrays. Use `mapAttributes` for dynamic key/value mappings and `attributePaths` to list the Mongoose fields that should trigger an attribute resync. Existing unmanaged Keycloak attributes are preserved, including when a user is resolved by email. Set `managedAttributes` to the keys this plugin owns; managed keys are replaced by the mapper result and removed when omitted, returned as `null`/`undefined`, returned as an empty array, or mapped to unsupported object values. Attribute keys named `__proto__`, `prototype`, or `constructor` are rejected.
 
-Password sync is disabled by default to avoid sending stored password hashes to Keycloak. Enable it only when the mapped value is the plaintext password intended for Keycloak, such as a short-lived `pendingPassword` field. Passwords are never included in user-create or profile-update payloads; both newly created users and existing users are updated through Keycloak's reset-password endpoint with the configured `passwordTemporary` value. The plugin stores a newly resolved Keycloak user ID before optional password, role, and verification-email work so a later retry can converge on the same remote user instead of creating a duplicate. The application owns the lifecycle of plaintext password fields: keep them short-lived and prevent them from being persisted, logged, traced, or sent to error reporters beyond the intended Keycloak operation.
+Mapper dependencies are explicit: `attributePaths`, `rolePaths`, and `passwordPaths` declare the extra Mongoose paths that trigger the `attributes`/`roles`/`password` operations when `mapAttributes`/`mapRoles`/`mapPassword` read beyond their configured paths (as with the `tier` and virtual `pendingPassword` inputs above). Dependencies are honored only while the corresponding `syncFields` entry is enabled; disabled fields stay fully inert. Dependency arrays are validated and snapshotted at registration. The password mapper is evaluated lazily — only for creation (new remote user, exactly once, with the value reused by the same-save recovery attempt) or when a declared password change indicates actual password-sync intent — so unrelated updates never invoke it and never reset credentials; likewise `mapRoles` runs only inside role sync for creations or `roles` changes.
+
+Password sync is disabled by default to avoid sending stored password hashes to Keycloak. Enable it only when the mapped value is a short-lived, non-persisted plaintext input such as the `pendingPassword` virtual above — never an ordinary stored plaintext schema path. Passwords are never included in user-create or profile-update payloads; both newly created users and existing users are updated through Keycloak's reset-password endpoint with the configured `passwordTemporary` value. The plugin stores a newly resolved Keycloak user ID before optional password, role, and verification-email work so a later retry can converge on the same remote user instead of creating a duplicate. A partially provisioned account stays disabled until its required credentials succeed: profile updates never carry `enabled`, and enablement follows the credential reset. The application owns the lifecycle of plaintext password inputs: keep them short-lived and non-persisted, and prevent them from being logged, traced, or sent to error reporters beyond the intended Keycloak operation.
 
-Errors are logged to `console.error` and rethrown by default. The default logger context is redacted to safe metadata such as `operation` and `localDocumentId`; it never includes the Mongoose document, profile payload, email address, or password. `onError` receives the same safe context by default. Set `includeDocumentInErrorContext: true` only for private handlers that are allowed to receive the full Mongoose document, which can contain plaintext passwords, email addresses, attributes, and arbitrary application fields. Logger and `onError` failures do not replace the original Keycloak sync error; with `throwOnError: false`, those observer failures are best-effort and are swallowed.
+Errors are logged to `console.error` and rethrown by default. The logger boundary receives only an allowlisted summary — `{ operation, localDocumentId, error: { name, code?, status? } }` with a validated error name and optional machine codes — and never the message, stack, cause, request/response data, or arbitrary error properties, so transport secrets cannot flow into logs. `onError` still receives the original error for private processing with the same safe context by default. Set `includeDocumentInErrorContext: true` only for private handlers that are allowed to receive the full Mongoose document, which can contain plaintext passwords, email addresses, attributes, and arbitrary application fields. Logger and `onError` failures do not replace the original Keycloak sync error; with `throwOnError: false`, those observer failures are best-effort and are swallowed.
 
 Only document `save()` and document `deleteOne()` are intercepted. Query operations such as `updateOne()`, `findOneAndUpdate()`, and query `deleteOne()` bypass the plugin. The selected delivery contract is direct, non-atomic hooks: Keycloak work is not part of the MongoDB commit, and the plugin rejects documents saved or deleted with a Mongoose session or transaction. Applications that need transactional delivery should write their own outbox intent in the MongoDB transaction and process it after commit.
 

package/index.d.mts

@@ -1,6 +1,6 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './plugins/model-function.mjs';
-export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, cascadeDeletePlugin } from './plugins/cascade-delete.mjs';
+export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, QueryOperators, cascadeDeletePlugin } from './plugins/cascade-delete.mjs';
 export { NewDocumentPluginOptions, newDocumentPlugin } from './plugins/new-document.mjs';
-export { uniqueEmptiableString, uniqueNullableString } from './schema.mjs';
+export { SchemaOptionOverrides, uniqueEmptiableString, uniqueNullableString } from './schema.mjs';
 export { isObjectId } from './is.mjs';
 import 'mongoose';

package/index.d.ts

@@ -1,6 +1,6 @@
 export { ModelDocument, ModelFunctionInstanceMethods, ModelFunctionPluginOptions, ModelFunctionStaticMethods, modelFunctionPlugin } from './plugins/model-function.js';
-export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, cascadeDeletePlugin } from './plugins/cascade-delete.js';
+export { CascadeDeleteDependencyMap, CascadeDeleteDocumentMethods, CascadeDeleteModelStatics, CascadeDeletePluginOptions, FilterResolver, QueryFilter, QueryOperators, cascadeDeletePlugin } from './plugins/cascade-delete.js';
 export { NewDocumentPluginOptions, newDocumentPlugin } from './plugins/new-document.js';
-export { uniqueEmptiableString, uniqueNullableString } from './schema.js';
+export { SchemaOptionOverrides, uniqueEmptiableString, uniqueNullableString } from './schema.js';
 export { isObjectId } from './is.js';
 import 'mongoose';