@web-ts-toolkit/moo 0.43.0 → 0.48.0

package/plugins/keycloak-user-sync.mjs

@@ -54,12 +54,24 @@ var normalizeAttributes = (attributes) => {
   return normalizedAttributes;
 };
 var getDocumentValue = (document, paths, field) => document.get(paths[field]);
+var dependencyPathsFor = (options, field) => {
+  if (!options.syncFields[field]) return [];
+  if (field === "attributes") return options.attributePaths ?? [];
+  if (field === "roles") return options.rolePaths ?? [];
+  return options.passwordPaths ?? [];
+};
+var hasDependencyChanged = (options, field, isModified) => dependencyPathsFor(options, field).some(isModified);
+var collectDependencyPaths = (options) => [
+  ...dependencyPathsFor(options, "attributes"),
+  ...dependencyPathsFor(options, "roles"),
+  ...dependencyPathsFor(options, "password")
+];
 var buildTrackedPaths = (options) => uniqueStrings([
   options.paths.providerId,
   ...Object.entries(options.syncFields).filter(([, enabled]) => enabled).flatMap(
     ([field]) => field === "enabled" ? [options.paths.enabled, options.paths.archived] : [options.paths[field]]
   ),
-  ...options.syncFields.attributes && options.attributePaths ? options.attributePaths : []
+  ...collectDependencyPaths(options)
 ]);
 var planChangedFields = (options, isNew, isModified, currentProviderId) => {
   const changedFields = /* @__PURE__ */ new Set();
@@ -69,7 +81,9 @@ var planChangedFields = (options, isNew, isModified, currentProviderId) => {
     const paths = field === "enabled" ? [options.paths.enabled, options.paths.archived] : [options.paths[field]];
     if (paths.some(isModified)) changedFields.add(field);
   }
-  if (options.syncFields.attributes && options.attributePaths?.some(isModified)) changedFields.add("attributes");
+  if (hasDependencyChanged(options, "attributes", isModified)) changedFields.add("attributes");
+  if (hasDependencyChanged(options, "roles", isModified)) changedFields.add("roles");
+  if (hasDependencyChanged(options, "password", isModified)) changedFields.add("password");
   const shouldPersistMissingProviderId = stringValue(currentProviderId) === null;
   const shouldSync = isNew || shouldPersistMissingProviderId || changedFields.size > 0;
   return {
@@ -288,6 +302,8 @@ var normalizeOptions = (schema, options) => {
     paths,
     syncFields,
     attributePaths: normalizeOptionalStringList(options.attributePaths, "attributePaths"),
+    rolePaths: normalizeOptionalStringList(options.rolePaths, "rolePaths"),
+    passwordPaths: normalizeOptionalStringList(options.passwordPaths, "passwordPaths"),
     managedAttributes: normalizeOptionalStringList(options.managedAttributes, "managedAttributes"),
     managedRoles: normalizeOptionalStringList(options.managedRoles, "managedRoles"),
     maxRolesPerSync: normalizeMaxRolesPerSync(options.maxRolesPerSync)
@@ -311,6 +327,26 @@ var normalizeOptions = (schema, options) => {
   return normalized;
 };
 var getState = (document) => document.$locals[syncStateKey];
+var loggerTokenPattern = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+var toLoggerToken = (value) => {
+  if (typeof value !== "string") return void 0;
+  if (value.length === 0 || value.length > 64) return void 0;
+  if (!loggerTokenPattern.test(value)) return void 0;
+  return value;
+};
+var toLoggedError = (error) => {
+  if (typeof error !== "object" || error === null) return { name: "UnknownError" };
+  try {
+    const candidate = error;
+    const name = toLoggerToken(candidate.name) ?? "Error";
+    const code = toLoggerToken(candidate.code);
+    const rawStatus = candidate.status ?? candidate.statusCode;
+    const status = typeof rawStatus === "number" && Number.isSafeInteger(rawStatus) && rawStatus >= 0 && rawStatus <= 999 ? rawStatus : void 0;
+    return { name, ...code === void 0 ? {} : { code }, ...status === void 0 ? {} : { status } };
+  } catch {
+    return { name: "Error" };
+  }
+};
 var getDocumentSession = (document) => document.$session?.() ?? null;
 var assertNoDocumentSession = (document, operation) => {
   if (getDocumentSession(document)) {
@@ -331,6 +367,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
   const identities = options.identifyBy;
   const realmHandle = options.client.realm(options.realm);
   const trackedPaths = buildTrackedPaths(options);
+  const identitySnapshotPaths = uniqueStrings([...trackedPaths, paths.providerId, paths.username, paths.email]);
   const buildSafeErrorContext = (operation, document) => ({
     operation,
     localDocumentId: document._id === void 0 || document._id === null ? void 0 : String(document._id)
@@ -339,7 +376,10 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
     const safeContext = buildSafeErrorContext(operation, document);
     const logger = options.logger === false ? null : options.logger ?? console;
     try {
-      await logger?.error(`Keycloak user sync failed during ${operation}`, { ...safeContext, error });
+      await logger?.error(`Keycloak user sync failed during ${operation}`, {
+        ...safeContext,
+        error: toLoggedError(error)
+      });
     } catch {
     }
     try {
@@ -352,7 +392,8 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
   const readDocumentValue = (document, field) => getDocumentValue(document, paths, field);
   const getPreviousValue = (previous, field) => getPathValue(previous, paths[field]);
   const getUsername = (document) => stringValue(readDocumentValue(document, "username")) ?? stringValue(readDocumentValue(document, "email"));
-  const resolveUser = async (document, previous) => {
+  const readPersistedSnapshot = async (document) => document.constructor.findById(document._id).select(identitySnapshotPaths).session(getDocumentSession(document)).lean();
+  const resolveUser = async (document, snapshot, wasNew) => {
     const realm = await realmHandle.get();
     if (!realm) throw new Error(`Keycloak realm "${options.realm}" was not found`);
     const duplicateEmailsAllowed = realm.duplicateEmailsAllowed === true;
@@ -361,40 +402,133 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
       if (!user.id) return user;
       return await realmHandle.userById(user.id).get() ?? user;
     };
-    for (const identity of orderedIdentities) {
-      if (identity === "providerId") {
-        for (const providerId of uniqueStrings([
-          readDocumentValue(document, "providerId"),
-          getPreviousValue(previous, "providerId")
-        ])) {
-          const user = await realmHandle.userById(providerId).get();
-          if (user) return { user, duplicateEmailsAllowed };
-        }
+    const findByProviderId = async (providerId) => realmHandle.userById(providerId).get();
+    const findByUsername = async (username) => realmHandle.user(username).get();
+    const findByEmail = async (email) => {
+      const matches = (await realmHandle.searchUsers(email, { attribute: "email", exact: true, first: 0, max: 2 })).filter((user) => normalizeEmail(user.email) === normalizeEmail(email));
+      if (matches.length > 1) {
+        throw new Error("Cannot identify a unique Keycloak user for the configured email identity");
       }
-      if (identity === "username") {
-        for (const username of uniqueStrings([
-          readDocumentValue(document, "username"),
-          getPreviousValue(previous, "username")
+      if (matches.length === 1) return getCompleteUserById(matches[0]);
+      return null;
+    };
+    const findByIdentity = async (identity, value) => {
+      if (identity === "providerId") return findByProviderId(value);
+      if (identity === "username") return findByUsername(value);
+      return findByEmail(value);
+    };
+    const identityConflict = () => new Error(
+      "keycloakUserSyncPlugin detected a Keycloak identity conflict; refusing to relink to a different remote user"
+    );
+    if (wasNew) {
+      for (const identity of orderedIdentities) {
+        for (const value of uniqueStrings([
+          readDocumentValue(document, identity),
+          getPreviousValue(snapshot, identity)
         ])) {
-          const user = await realmHandle.user(username).get();
+          const user = await findByIdentity(identity, value);
           if (user) return { user, duplicateEmailsAllowed };
         }
       }
-      if (identity === "email") {
-        for (const email of uniqueStrings([
-          readDocumentValue(document, "email"),
-          getPreviousValue(previous, "email")
-        ])) {
-          const matches = (await realmHandle.searchUsers(email, { attribute: "email", exact: true, first: 0, max: 2 })).filter((user) => normalizeEmail(user.email) === normalizeEmail(email));
-          if (matches.length > 1) {
-            throw new Error("Cannot identify a unique Keycloak user for the configured email identity");
-          }
-          if (matches.length === 1) return { user: await getCompleteUserById(matches[0]), duplicateEmailsAllowed };
-        }
+      return { user: null, duplicateEmailsAllowed };
+    }
+    if (!snapshot) {
+      throw new Error(
+        "keycloakUserSyncPlugin cannot verify the persisted Keycloak identity for this document; refusing to sync a possibly relinked account"
+      );
+    }
+    const persistedValue = (identity) => stringValue(getPreviousValue(snapshot, identity));
+    const currentValue = (identity) => stringValue(readDocumentValue(document, identity));
+    const persistedProviderId = persistedValue("providerId");
+    const currentProviderId = currentValue("providerId");
+    if (persistedProviderId && currentProviderId && persistedProviderId !== currentProviderId) {
+      throw new Error("keycloakUserSyncPlugin providerId is server-controlled and cannot be changed after persistence");
+    }
+    const isRelinkProtected = (identity) => identity === "username" || identity === "email" && !duplicateEmailsAllowed;
+    const checkCurrentDoesNotRelink = async (identity, boundId) => {
+      if (!identities.includes(identity) || !isRelinkProtected(identity)) return;
+      const current = currentValue(identity);
+      if (!current) return;
+      const persisted = persistedValue(identity);
+      const unchanged = identity === "email" ? persisted !== null && normalizeEmail(persisted) === normalizeEmail(current) : persisted === current;
+      if (persisted !== null && unchanged) return;
+      const user = await findByIdentity(identity, current);
+      if (user?.id && user.id !== boundId) throw identityConflict();
+    };
+    if (persistedProviderId) {
+      const bound2 = await findByProviderId(persistedProviderId);
+      if (!bound2?.id) {
+        throw new Error(
+          "keycloakUserSyncPlugin persisted Keycloak identity no longer exists; refusing to relink to a different remote user"
+        );
+      }
+      await checkCurrentDoesNotRelink("username", bound2.id);
+      await checkCurrentDoesNotRelink("email", bound2.id);
+      return { user: bound2, duplicateEmailsAllowed };
+    }
+    let bound = null;
+    for (const identity of orderedIdentities) {
+      if (identity === "providerId") continue;
+      const persisted = persistedValue(identity);
+      if (!persisted) continue;
+      const user = await findByIdentity(identity, persisted);
+      if (!user?.id) continue;
+      if (bound?.id && bound.id !== user.id) throw identityConflict();
+      bound ??= user;
+    }
+    if (bound?.id) {
+      await checkCurrentDoesNotRelink("username", bound.id);
+      await checkCurrentDoesNotRelink("email", bound.id);
+      if (currentProviderId) {
+        const owner = await findByProviderId(currentProviderId);
+        if (owner?.id && owner.id !== bound.id) throw identityConflict();
       }
+      return { user: bound, duplicateEmailsAllowed };
+    }
+    if (currentProviderId) {
+      const owner = await findByProviderId(currentProviderId);
+      if (owner?.id) throw identityConflict();
+    }
+    for (const identity of orderedIdentities) {
+      if (identity === "providerId") continue;
+      const current = currentValue(identity);
+      if (!current) continue;
+      const user = await findByIdentity(identity, current);
+      if (user?.id) throw identityConflict();
     }
     return { user: null, duplicateEmailsAllowed };
   };
+  const getProvisioningFlags = (error) => {
+    if (typeof error !== "object" || error === null) return null;
+    const candidate = error;
+    if (candidate.name !== "UserPasswordProvisioningError" && !("accountPersists" in candidate) && !("initialProvisioning" in candidate)) {
+      return null;
+    }
+    return candidate;
+  };
+  const isAlreadyExistsError = (error) => error instanceof Error && /already exists in realm/.test(error.message);
+  const readIntendedEnabled = (document) => {
+    if (!syncFields.enabled) return void 0;
+    const archived = readDocumentValue(document, "archived");
+    if (typeof archived === "boolean") return !archived;
+    const enabled = readDocumentValue(document, "enabled");
+    if (typeof enabled === "boolean") return enabled;
+    return void 0;
+  };
+  const recoverPartialCreation = async (document, username, creationError, desiredPassword) => {
+    if (identities.length === 0) throw creationError;
+    if (isAlreadyExistsError(creationError)) throw creationError;
+    const flags = getProvisioningFlags(creationError);
+    if (flags && flags.accountPersists === false) throw creationError;
+    if (desiredPassword && !(flags && flags.accountPersists === true)) throw creationError;
+    const recoveredUser = await resolveCreatedUser(document, username);
+    if (!recoveredUser?.id) throw creationError;
+    if (desiredPassword) {
+      const candidateUsername = stringValue(recoveredUser.username);
+      if (!candidateUsername || candidateUsername !== username) throw creationError;
+    }
+    return { user: recoveredUser, passwordAlreadyApplied: flags?.passwordApplied === true };
+  };
   const resolveCreatedUser = async (document, username) => {
     const userByUsername = await realmHandle.user(username).get();
     if (userByUsername) return userByUsername;
@@ -432,34 +566,46 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
     document.unmarkModified(paths.providerId);
   };
   const syncDocument = async (document, state) => {
-    const resolved = await resolveUser(document, state.previous);
+    const resolved = await resolveUser(document, state.previous, state.wasNew);
     let user = resolved.user;
     let created = false;
+    let recoveredPartial = false;
+    let passwordAlreadyApplied = false;
     const shouldSyncProfile = state.wasNew || ["username", "email", "emailVerified", "firstName", "lastName", "enabled"].some(
       (field) => state.changedFields.has(field)
     );
     const shouldSyncAttributes = state.wasNew || state.changedFields.has("attributes");
     const payload = shouldSyncProfile ? buildProfilePayload(document, options, Boolean(resolved.user), state.wasNew ? void 0 : state.changedFields) : {};
-    const desiredPassword = getDesiredPassword(document, options);
+    let cachedPassword;
+    let passwordEvaluated = false;
+    const readDesiredPassword = () => {
+      if (!passwordEvaluated) {
+        cachedPassword = getDesiredPassword(document, options);
+        passwordEvaluated = true;
+      }
+      return cachedPassword ?? null;
+    };
     if (!user) {
       const username = getUsername(document);
       if (!username) throw new Error("Cannot create a Keycloak user without a username or email");
       payload.attributes = mergeAttributes(null, document, options);
+      const creationPassword = readDesiredPassword();
       try {
         user = await realmHandle.user(username).create({
           username,
           ...payload,
-          ...desiredPassword && {
-            password: desiredPassword,
+          ...creationPassword && {
+            password: creationPassword,
             passwordTemporary: options.passwordTemporary ?? false
           }
         }) ?? null;
         created = true;
       } catch (error) {
-        if (identities.length === 0) throw error;
-        const recoveredUser = await resolveCreatedUser(document, username);
-        if (!recoveredUser) throw error;
-        user = recoveredUser;
+        if (!state.wasNew) throw error;
+        const recovered = await recoverPartialCreation(document, username, error, creationPassword);
+        user = recovered.user;
+        recoveredPartial = true;
+        passwordAlreadyApplied = recovered.passwordAlreadyApplied;
       }
     }
     if (!user?.id) throw new Error("Keycloak did not return a user ID");
@@ -474,6 +620,8 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
       currentEmail: readDocumentValue(document, "email"),
       remoteEmail: user.email
     });
+    const desiredPassword = !created && !passwordAlreadyApplied && (recoveredPartial || state.passwordChanged) ? readDesiredPassword() : cachedPassword ?? null;
+    const willResetPassword = Boolean(desiredPassword) && !created && !passwordAlreadyApplied && (recoveredPartial || state.passwordChanged);
     if (!created) {
       if (emailVerificationPlan.initialLinkSameEmail) delete payload.emailVerified;
       if (emailVerificationPlan.changed) {
@@ -482,21 +630,35 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
         payload.emailVerified = false;
       }
       if (shouldSyncAttributes) payload.attributes = mergeAttributes(user, document, options);
-      if (Object.keys(payload).length > 0) {
-        await realmHandle.userById(userId).update(payload);
-        user = { ...user, ...payload };
+      if (willResetPassword) {
+        const { enabled: deferredEnabled, ...profileWithoutEnabled } = payload;
+        const intendedEnabled = typeof deferredEnabled === "boolean" ? deferredEnabled : readIntendedEnabled(document) ?? true;
+        if (Object.keys(profileWithoutEnabled).length > 0) {
+          await realmHandle.userById(userId).update(profileWithoutEnabled);
+          user = { ...user, ...profileWithoutEnabled };
+        }
+        await realmHandle.userById(userId).resetPassword(desiredPassword, { temporary: options.passwordTemporary ?? false });
+        user = { ...user };
+        await realmHandle.userById(userId).update({ enabled: intendedEnabled });
+        user = { ...user, enabled: intendedEnabled };
+      } else {
+        if (Object.keys(payload).length > 0) {
+          await realmHandle.userById(userId).update(payload);
+          user = { ...user, ...payload };
+        }
       }
     }
-    if (!created && state.passwordChanged && desiredPassword) {
-      await realmHandle.userById(userId).resetPassword(desiredPassword, { temporary: options.passwordTemporary ?? false });
-    }
     if (created || state.changedFields.has("roles")) await syncRoles(user, document);
     if (emailVerificationPlan.changed && options.sendVerificationEmailOnChange !== false) {
       await realmHandle.userById(userId).sendVerifyEmail();
     }
   };
   const deleteDocument = async (document) => {
-    const { user } = await resolveUser(document);
+    if (document.isNew) {
+      throw new Error("keycloakUserSyncPlugin cannot delete a Keycloak user for a document that was never persisted");
+    }
+    const snapshot = await readPersistedSnapshot(document);
+    const { user } = await resolveUser(document, snapshot, false);
     if (user?.id) await realmHandle.userById(user.id).delete();
   };
   schema.pre("save", async function keycloakUserSyncPreSave() {
@@ -511,7 +673,7 @@ function keycloakUserSyncPlugin(schema, rawOptions) {
     const state = { ...changePlan, wasNew: this.isNew };
     this.$locals[syncStateKey] = state;
     if (!state.shouldSync || this.isNew) return;
-    state.previous = await this.constructor.findById(this._id).select(trackedPaths).session(getDocumentSession(this)).lean();
+    state.previous = await readPersistedSnapshot(this);
     if (providerIdChanged) {
       const previousProviderId = stringValue(getPreviousValue(state.previous, "providerId"));
       const currentProviderId = stringValue(readDocumentValue(this, "providerId"));

package/plugins/model-function.d.mts

@@ -1,9 +1,23 @@
 import { HydratedDocument, Types, Schema, Model } from 'mongoose';
 
+/**
+ * Hydrated document for a raw doc type with the given instance methods.
+ */
 type ModelDocument<TRawDocType, TInstanceMethods = Record<string, never>> = HydratedDocument<TRawDocType, TInstanceMethods>;
+/**
+ * Instance-method surface added by one `modelFunctionPlugin` registration.
+ * Keep method result types free of the enclosing `ModelDocument` alias (use
+ * `void` for in-place mutation or a plain value) to avoid circular
+ * `CartDocument`/`CartMethods` aliases, which fail with TS2456.
+ */
 type ModelFunctionInstanceMethods<TMethodName extends string, TArgs extends unknown[] = unknown[], TResult = unknown> = {
     [K in TMethodName]: (...args: TArgs) => TResult;
 };
+/**
+ * Static-method surface added by one registration: `fnName(doc, ...args)`
+ * plus the `fnNameById(docId, ...args)` loader, which returns `null` when no
+ * document matches.
+ */
 type ModelFunctionStaticMethods<TMethodName extends string, TDocument, TArgs extends unknown[] = unknown[], TResult = unknown> = {
     [K in TMethodName]: (doc: TDocument, ...args: TArgs) => TResult;
 } & {
@@ -13,6 +27,38 @@ interface ModelFunctionPluginOptions<TMethodName extends string, TDocument, TArg
     fnName: TMethodName;
     fn(doc: TDocument, ...args: TArgs): TResult;
 }
+/**
+ * Registers one sync or async helper as an instance method, a static method
+ * taking the document first, and a `ById` static that loads the document
+ * (returning `null` when missing) before invoking `fn`. The helper runs with
+ * the historical mongoose-bound callback context and receives the document
+ * as its first argument.
+ *
+ * Prefer inference over explicit generics: `schema.plugin(modelFunctionPlugin,
+ * { fnName, fn })` infers the method name, argument tuple, and result from
+ * the options. When explicit type arguments are needed, the second argument
+ * is the method *name* (`'applyDiscount'`), not the methods object. Keep
+ * `TResult` free of the enclosing document alias to avoid circular types.
+ *
+ * @example
+ * type Cart = { name: string; price: number };
+ * type CartMethods =
+ *   ModelFunctionInstanceMethods<'applyDiscount', [suffix: string, priceChange: number], void> &
+ *   ModelFunctionInstanceMethods<'applyDiscountAsync', [suffix: string, priceChange: number], Promise<void>>;
+ * type CartDocument = ModelDocument<Cart, CartMethods>;
+ * type CartModel = Model<Cart, Record<string, never>, CartMethods> &
+ *   ModelFunctionStaticMethods<'applyDiscount', CartDocument, [suffix: string, priceChange: number], void> &
+ *   ModelFunctionStaticMethods<'applyDiscountAsync', CartDocument, [suffix: string, priceChange: number], Promise<void>>;
+ *
+ * const cartSchema = new Schema<Cart, CartModel, CartMethods>({ name: String, price: Number });
+ * cartSchema.plugin(modelFunctionPlugin, {
+ *   fnName: 'applyDiscount',
+ *   fn: (cart: CartDocument, suffix: string, priceChange: number) => {
+ *     cart.name = `${cart.name}-${suffix}`;
+ *     cart.price += priceChange;
+ *   },
+ * });
+ */
 declare function modelFunctionPlugin<TRawDocType, TMethodName extends string = string, TInstanceMethods = Record<string, never>, TDocument = ModelDocument<TRawDocType, TInstanceMethods>, TArgs extends unknown[] = unknown[], TResult = unknown>(schema: Schema<TRawDocType, Model<TRawDocType>, TInstanceMethods>, options: ModelFunctionPluginOptions<TMethodName, TDocument, TArgs, TResult>): void;
 
 export { type ModelDocument, type ModelFunctionInstanceMethods, type ModelFunctionPluginOptions, type ModelFunctionStaticMethods, modelFunctionPlugin };

package/plugins/model-function.d.ts

@@ -1,9 +1,23 @@
 import { HydratedDocument, Types, Schema, Model } from 'mongoose';
 
+/**
+ * Hydrated document for a raw doc type with the given instance methods.
+ */
 type ModelDocument<TRawDocType, TInstanceMethods = Record<string, never>> = HydratedDocument<TRawDocType, TInstanceMethods>;
+/**
+ * Instance-method surface added by one `modelFunctionPlugin` registration.
+ * Keep method result types free of the enclosing `ModelDocument` alias (use
+ * `void` for in-place mutation or a plain value) to avoid circular
+ * `CartDocument`/`CartMethods` aliases, which fail with TS2456.
+ */
 type ModelFunctionInstanceMethods<TMethodName extends string, TArgs extends unknown[] = unknown[], TResult = unknown> = {
     [K in TMethodName]: (...args: TArgs) => TResult;
 };
+/**
+ * Static-method surface added by one registration: `fnName(doc, ...args)`
+ * plus the `fnNameById(docId, ...args)` loader, which returns `null` when no
+ * document matches.
+ */
 type ModelFunctionStaticMethods<TMethodName extends string, TDocument, TArgs extends unknown[] = unknown[], TResult = unknown> = {
     [K in TMethodName]: (doc: TDocument, ...args: TArgs) => TResult;
 } & {
@@ -13,6 +27,38 @@ interface ModelFunctionPluginOptions<TMethodName extends string, TDocument, TArg
     fnName: TMethodName;
     fn(doc: TDocument, ...args: TArgs): TResult;
 }
+/**
+ * Registers one sync or async helper as an instance method, a static method
+ * taking the document first, and a `ById` static that loads the document
+ * (returning `null` when missing) before invoking `fn`. The helper runs with
+ * the historical mongoose-bound callback context and receives the document
+ * as its first argument.
+ *
+ * Prefer inference over explicit generics: `schema.plugin(modelFunctionPlugin,
+ * { fnName, fn })` infers the method name, argument tuple, and result from
+ * the options. When explicit type arguments are needed, the second argument
+ * is the method *name* (`'applyDiscount'`), not the methods object. Keep
+ * `TResult` free of the enclosing document alias to avoid circular types.
+ *
+ * @example
+ * type Cart = { name: string; price: number };
+ * type CartMethods =
+ *   ModelFunctionInstanceMethods<'applyDiscount', [suffix: string, priceChange: number], void> &
+ *   ModelFunctionInstanceMethods<'applyDiscountAsync', [suffix: string, priceChange: number], Promise<void>>;
+ * type CartDocument = ModelDocument<Cart, CartMethods>;
+ * type CartModel = Model<Cart, Record<string, never>, CartMethods> &
+ *   ModelFunctionStaticMethods<'applyDiscount', CartDocument, [suffix: string, priceChange: number], void> &
+ *   ModelFunctionStaticMethods<'applyDiscountAsync', CartDocument, [suffix: string, priceChange: number], Promise<void>>;
+ *
+ * const cartSchema = new Schema<Cart, CartModel, CartMethods>({ name: String, price: Number });
+ * cartSchema.plugin(modelFunctionPlugin, {
+ *   fnName: 'applyDiscount',
+ *   fn: (cart: CartDocument, suffix: string, priceChange: number) => {
+ *     cart.name = `${cart.name}-${suffix}`;
+ *     cart.price += priceChange;
+ *   },
+ * });
+ */
 declare function modelFunctionPlugin<TRawDocType, TMethodName extends string = string, TInstanceMethods = Record<string, never>, TDocument = ModelDocument<TRawDocType, TInstanceMethods>, TArgs extends unknown[] = unknown[], TResult = unknown>(schema: Schema<TRawDocType, Model<TRawDocType>, TInstanceMethods>, options: ModelFunctionPluginOptions<TMethodName, TDocument, TArgs, TResult>): void;
 
 export { type ModelDocument, type ModelFunctionInstanceMethods, type ModelFunctionPluginOptions, type ModelFunctionStaticMethods, modelFunctionPlugin };

package/plugins/new-document.d.mts

@@ -1,12 +1,31 @@
 import { HydratedDocument, Schema } from 'mongoose';
 
 interface NewDocumentPluginOptions<TDocument = unknown, TResult = unknown> {
-    /** Runs after the first successful save for a newly inserted document. */
+    /**
+     * Runs once, after the first successful `save()` of a newly inserted
+     * document. This is a post-save notification, not durable delivery: a
+     * throwing callback rejects the post-save hook but cannot roll back the
+     * committed write, and no outbox, retry, or exactly-once guarantee across
+     * transaction retries is provided. Applications needing transactional
+     * delivery should record their own outbox intent and process it after
+     * commit.
+     */
     fn(this: TDocument, document: TDocument): TResult | Promise<TResult>;
 }
 /**
  * Runs a callback once, after a newly inserted document is successfully saved.
- * Existing documents saved later do not trigger the callback.
+ *
+ * Supported operations: only document `save()` is observed, via 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. Later saves of the same
+ * document do not re-trigger it.
+ *
+ * Delivery scope: post-save notification, not durable delivery. The callback
+ * runs after MongoDB persistence; its failure cannot roll back the write,
+ * and transaction retries/reentrant saves carry no exactly-once guarantee.
+ * Write an application-owned outbox record inside the transaction when
+ * exactly-once downstream delivery is required.
  */
 declare function newDocumentPlugin<TRawDocType, TDocument = HydratedDocument<TRawDocType>>(schema: Schema<TRawDocType>, options: NewDocumentPluginOptions<TDocument>): void;
 

package/plugins/new-document.d.ts

@@ -1,12 +1,31 @@
 import { HydratedDocument, Schema } from 'mongoose';
 
 interface NewDocumentPluginOptions<TDocument = unknown, TResult = unknown> {
-    /** Runs after the first successful save for a newly inserted document. */
+    /**
+     * Runs once, after the first successful `save()` of a newly inserted
+     * document. This is a post-save notification, not durable delivery: a
+     * throwing callback rejects the post-save hook but cannot roll back the
+     * committed write, and no outbox, retry, or exactly-once guarantee across
+     * transaction retries is provided. Applications needing transactional
+     * delivery should record their own outbox intent and process it after
+     * commit.
+     */
     fn(this: TDocument, document: TDocument): TResult | Promise<TResult>;
 }
 /**
  * Runs a callback once, after a newly inserted document is successfully saved.
- * Existing documents saved later do not trigger the callback.
+ *
+ * Supported operations: only document `save()` is observed, via 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. Later saves of the same
+ * document do not re-trigger it.
+ *
+ * Delivery scope: post-save notification, not durable delivery. The callback
+ * runs after MongoDB persistence; its failure cannot roll back the write,
+ * and transaction retries/reentrant saves carry no exactly-once guarantee.
+ * Write an application-owned outbox record inside the transaction when
+ * exactly-once downstream delivery is required.
  */
 declare function newDocumentPlugin<TRawDocType, TDocument = HydratedDocument<TRawDocType>>(schema: Schema<TRawDocType>, options: NewDocumentPluginOptions<TDocument>): void;
 

package/schema.d.mts

@@ -1,10 +1,17 @@
+/**
+ * Arbitrary Mongoose schema-type options merged over the helper defaults.
+ * Provided keys win over the defaults at runtime via object spread; the
+ * helpers type this with `Omit<Base, keyof TOverrides> & TOverrides` so an
+ * override of `default`, `trim`, or `index` is reflected in the inferred
+ * return type instead of keeping the fixed default type.
+ */
 type SchemaOptionOverrides = Record<string, unknown>;
-declare const uniqueNullableString: (field: string, options?: SchemaOptionOverrides) => {
+type UniqueNullableBase = {
     type: StringConstructor;
     index: {
         unique: boolean;
         partialFilterExpression: {
-            [x: string]: {
+            [field: string]: {
                 $type: string;
             };
         };
@@ -12,12 +19,12 @@ declare const uniqueNullableString: (field: string, options?: SchemaOptionOverri
     trim: boolean;
     default: null;
 };
-declare const uniqueEmptiableString: (field: string, options?: SchemaOptionOverrides) => {
+type UniqueEmptiableBase = {
     type: StringConstructor;
     index: {
         unique: boolean;
         partialFilterExpression: {
-            [x: string]: {
+            [field: string]: {
                 $type: string;
                 $gt: string;
             };
@@ -26,5 +33,27 @@ declare const uniqueEmptiableString: (field: string, options?: SchemaOptionOverr
     trim: boolean;
     default: null;
 };
+/**
+ * Partial-unique string field that allows any number of `null` values while
+ * still rejecting duplicate non-null strings (including `''`). The partial
+ * index only covers string-typed values (`{ [field]: { $type: 'string' } }`),
+ * so `null`/missing entries never conflict. Extra `options` are spread over
+ * the defaults and reflected in the return type.
+ *
+ * @example
+ * const userSchema = new Schema({ email: uniqueNullableString('email') });
+ */
+declare const uniqueNullableString: <TOverrides extends SchemaOptionOverrides = Record<string, never>>(field: string, options?: TOverrides) => Omit<UniqueNullableBase, keyof TOverrides> & TOverrides;
+/**
+ * Partial-unique string field that additionally ignores empty strings:
+ * both `null` and `''` can repeat, while duplicate non-empty strings are
+ * rejected. The partial index only covers strings longer than `''`
+ * (`{ [field]: { $type: 'string', $gt: '' } }`). Extra `options` are spread
+ * over the defaults and reflected in the return type.
+ *
+ * @example
+ * const userSchema = new Schema({ username: uniqueEmptiableString('username') });
+ */
+declare const uniqueEmptiableString: <TOverrides extends SchemaOptionOverrides = Record<string, never>>(field: string, options?: TOverrides) => Omit<UniqueEmptiableBase, keyof TOverrides> & TOverrides;
 
-export { uniqueEmptiableString, uniqueNullableString };
+export { type SchemaOptionOverrides, uniqueEmptiableString, uniqueNullableString };