@bedrockio/model 0.19.3 → 0.20.1

package/types/modules/soft-delete.d.ts

@@ -0,0 +1,458 @@
+import type { HydratedDocument } from 'mongoose';
+
+declare module 'mongoose' {
+  interface Model<
+    TRawDocType,
+    TQueryHelpers = {},
+    TInstanceMethods = {},
+    TVirtuals = {},
+    THydratedDocumentType = HydratedDocument<
+      TRawDocType,
+      TVirtuals & TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals
+    >,
+    TSchema = any,
+  > {
+    /**
+     * Soft deletes one document by setting deleted=true and deletedAt timestamp.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object>}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `acknowledged` | `boolean` | Whether the operation was acknowledged |
+     * | `deletedCount` | `number` | Number of documents deleted |
+     *
+     * @example
+     * ```js
+     * const result = await User.deleteOne({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    deleteOne(
+      filter: any,
+      options?: any,
+    ): Promise<{ acknowledged: boolean; deletedCount: number }>;
+
+    /**
+     * Soft deletes multiple documents by setting deleted=true and deletedAt timestamp.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object>}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `acknowledged` | `boolean` | Whether the operation was acknowledged |
+     * | `deletedCount` | `number` | Number of documents deleted |
+     *
+     * @example
+     * ```js
+     * const result = await User.deleteMany({
+     *   inactive: true
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    deleteMany(
+      filter: any,
+      options?: any,
+    ): Promise<{ acknowledged: boolean; deletedCount: number }>;
+
+    /**
+     * Finds and soft deletes one document, returning the deleted document.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Document|null>} - The deleted document or null
+     *
+     * @example
+     * ```js
+     * const user = await User.findOneAndDelete({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    findOneAndDelete(filter: any, options?: any): Promise<any>;
+
+    /**
+     * Restores one soft-deleted document by setting deleted=false and unsetting deletedAt.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object>}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `acknowledged` | `boolean` | Whether the operation was acknowledged |
+     * | `restoredCount` | `number` | Number of documents restored |
+     *
+     * @example
+     * ```js
+     * const result = await User.restoreOne({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    restoreOne(
+      filter: any,
+      options?: any,
+    ): Promise<{ acknowledged: boolean; restoredCount: number }>;
+
+    /**
+     * Restores multiple soft-deleted documents by setting deleted=false and unsetting deletedAt.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object>}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `acknowledged` | `boolean` | Whether the operation was acknowledged |
+     * | `restoredCount` | `number` | Number of documents restored |
+     *
+     * @example
+     * ```js
+     * const result = await User.restoreMany({
+     *   deletedAt: {
+     *     $gte: oneWeekAgo
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    restoreMany(
+      filter: any,
+      options?: any,
+    ): Promise<{ acknowledged: boolean; restoredCount: number }>;
+
+    /**
+     * Permanently deletes one document from the database (hard delete).
+     *
+     * @param {Object} conditions - Query conditions
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object>}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `acknowledged` | `boolean` | Whether the operation was acknowledged |
+     * | `destroyedCount` | `number` | Number of documents destroyed |
+     *
+     * @example
+     * ```js
+     * const result = await User.destroyOne({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    destroyOne(
+      conditions: any,
+      options?: any,
+    ): Promise<{ acknowledged: boolean; destroyedCount: number }>;
+
+    /**
+     * Permanently deletes multiple documents from the database (hard delete).
+     *
+     * @param {Object} conditions - Query conditions
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object>}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `acknowledged` | `boolean` | Whether the operation was acknowledged |
+     * | `destroyedCount` | `number` | Number of documents destroyed |
+     *
+     * @example
+     * ```js
+     * const result = await User.destroyMany({
+     *   deletedAt: {
+     *     $lt: sixMonthsAgo
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    destroyMany(
+      conditions: any,
+      options?: any,
+    ): Promise<{ acknowledged: boolean; destroyedCount: number }>;
+
+    /**
+     * Finds documents that have been soft-deleted (deleted=true).
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [projection] - Fields to include/exclude
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Document[]>} - Array of deleted documents
+     *
+     * @example
+     * ```js
+     * const deletedUsers = await User.findDeleted({
+     *   deletedAt: {
+     *     $gte: lastMonth
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    findDeleted(filter: any, projection?: any, options?: any): Promise<any[]>;
+
+    /**
+     * Finds one document that has been soft-deleted (deleted=true).
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [projection] - Fields to include/exclude
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Document|null>} - The deleted document or null
+     *
+     * @example
+     * ```js
+     * const user = await User.findOneDeleted({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    findOneDeleted(filter: any, projection?: any, options?: any): Promise<any>;
+
+    /**
+     * Finds a soft-deleted document by its ID.
+     *
+     * @param {string} id - Document ID
+     * @param {Object} [projection] - Fields to include/exclude
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Document|null>} - The deleted document or null
+     *
+     * @example
+     * ```js
+     * const user = await User.findByIdDeleted('507f1f77bcf86cd799439011');
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    findByIdDeleted(id: any, projection?: any, options?: any): Promise<any>;
+
+    /**
+     * Checks if a soft-deleted document exists matching the filter.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object|null>} - Object with _id if exists, null otherwise
+     *
+     * @example
+     * ```js
+     * const exists = await User.existsDeleted({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    existsDeleted(filter: any, options?: any): Promise<any>;
+
+    /**
+     * Counts soft-deleted documents matching the filter.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<number>} - Count of deleted documents
+     *
+     * @example
+     * ```js
+     * const count = await User.countDocumentsDeleted({
+     *   deletedAt: {
+     *     $gte: lastMonth
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    countDocumentsDeleted(filter: any, options?: any): Promise<number>;
+
+    /**
+     * Finds documents including both deleted and non-deleted ones.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [projection] - Fields to include/exclude
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Document[]>} - Array of documents
+     *
+     * @example
+     * ```js
+     * const allUsers = await User.findWithDeleted({
+     *   email: {
+     *     $regex: '@example.com$'
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    findWithDeleted(
+      filter: any,
+      projection?: any,
+      options?: any,
+    ): Promise<any[]>;
+
+    /**
+     * Finds one document including both deleted and non-deleted ones.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [projection] - Fields to include/exclude
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Document|null>} - The document or null
+     *
+     * @example
+     * ```js
+     * const user = await User.findOneWithDeleted({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    findOneWithDeleted(
+      filter: any,
+      projection?: any,
+      options?: any,
+    ): Promise<any>;
+
+    /**
+     * Finds a document by ID including both deleted and non-deleted ones.
+     *
+     * @param {string} id - Document ID
+     * @param {Object} [projection] - Fields to include/exclude
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Document|null>} - The document or null
+     *
+     * @example
+     * ```js
+     * const user = await User.findByIdWithDeleted('507f1f77bcf86cd799439011');
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    findByIdWithDeleted(id: any, projection?: any, options?: any): Promise<any>;
+
+    /**
+     * Checks if a document exists (deleted or not) matching the filter.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<Object|null>} - Object with _id if exists, null otherwise
+     *
+     * @example
+     * ```js
+     * const exists = await User.existsWithDeleted({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    existsWithDeleted(filter: any, options?: any): Promise<any>;
+
+    /**
+     * Counts documents (deleted or not) matching the filter.
+     *
+     * @param {Object} filter - Query filter
+     * @param {Object} [options] - MongoDB options
+     *
+     * @returns {Promise<number>} - Count of documents
+     *
+     * @example
+     * ```js
+     * const count = await User.countDocumentsWithDeleted({
+     *   email: {
+     *     $regex: '@example.com$'
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    countDocumentsWithDeleted(filter: any, options?: any): Promise<number>;
+  }
+
+  interface Document {
+    /**
+     * Soft deletes this document by setting deleted=true and deletedAt timestamp, then saves without validation.
+     *
+     * @returns {Promise<Document>} - The saved document
+     *
+     * @example
+     * ```js
+     * await user.delete();
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    delete(): Promise<this>;
+
+    /**
+     * Restores this soft-deleted document by setting deleted=false and unsetting deletedAt, then saves with validation.
+     *
+     * @returns {Promise<Document>} - The saved document
+     *
+     * @example
+     * ```js
+     * await user.restore();
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    restore(): Promise<this>;
+
+    /**
+     * Permanently deletes this document from the database (hard delete).
+     *
+     * @param {...any} args - Additional arguments passed to destroyOne
+     *
+     * @returns {Promise<Object>} - Result object with acknowledged and destroyedCount
+     *
+     * @example
+     * ```js
+     * await user.destroy();
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#soft-delete}
+     */
+    destroy(
+      ...args: any[]
+    ): Promise<{ acknowledged: boolean; destroyedCount: number }>;
+  }
+}

package/types/modules/upsert.d.ts

@@ -0,0 +1,67 @@
+import type { HydratedDocument } from 'mongoose';
+
+declare module 'mongoose' {
+  interface Model<
+    TRawDocType,
+    TQueryHelpers = {},
+    TInstanceMethods = {},
+    TVirtuals = {},
+    THydratedDocumentType = HydratedDocument<
+      TRawDocType,
+      TVirtuals & TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals
+    >,
+    TSchema = any,
+  > {
+    /**
+     * Updates an existing document or creates a new one if not found. Runs document hooks.
+     *
+     * @param {Object} query - Query to find existing document
+     * @param {Object} [fields] - Fields to update/create (defaults to query if not provided)
+     *
+     * @returns {Promise<Document>} - The created or updated document
+     *
+     * @example
+     * ```js
+     * const user = await User.upsert(
+     *   {
+     *     email: 'user@example.com'
+     *   },
+     *   {
+     *     email: 'user@example.com',
+     *     name: 'John Doe'
+     *   }
+     * );
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#upsert}
+     */
+    upsert(query: any, fields?: any): Promise<any>;
+
+    /**
+     * Finds an existing document or creates a new one if not found. Does not update existing documents.
+     *
+     * @param {Object} query - Query to find existing document
+     * @param {Object} [fields] - Fields to create if not found (defaults to query if not provided)
+     *
+     * @returns {Promise<Document>} - The found or created document
+     *
+     * @example
+     * ```js
+     * const user = await User.findOrCreate(
+     *   {
+     *     email: 'user@example.com'
+     *   },
+     *   {
+     *     email: 'user@example.com',
+     *     name: 'John Doe'
+     *   }
+     * );
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#upsert}
+     */
+    findOrCreate(query: any, fields?: any): Promise<any>;
+  }
+}

package/types/modules/validation.d.ts

@@ -0,0 +1,145 @@
+import type { HydratedDocument } from 'mongoose';
+
+declare module 'mongoose' {
+  interface Model<
+    TRawDocType,
+    TQueryHelpers = {},
+    TInstanceMethods = {},
+    TVirtuals = {},
+    THydratedDocumentType = HydratedDocument<
+      TRawDocType,
+      TVirtuals & TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals
+    >,
+    TSchema = any,
+  > {
+    /**
+     * Returns a validation schema for creating new documents.
+     *
+     * @param {Object} [options] - Configuration options
+     *
+     * | | | |
+     * |---|---|---|
+     * | `stripEmpty` | `boolean` | Strip empty values (default: true) |
+     * | `applyUnique` | `boolean` | Apply unique field validation (default: true) |
+     * | `stripDeleted` | `boolean` | Strip deleted fields from schema (default: true) |
+     * | `allowIncludes` | `boolean` | Allow include parameter (default: false) |
+     * | `stripTimestamps` | `boolean` | Strip createdAt/updatedAt fields (default: true) |
+     * | `allowDefaultTags` | `boolean` | Tag default values for OpenAPI (default: true) |
+     * | `allowExpandedRefs` | `boolean` | Allow expanded object references (default: true) |
+     * | `requireWriteAccess` | `boolean` | Require write access validation (default: true) |
+     *
+     * @returns {Object} - Yada validation schema
+     *
+     * @example
+     * ```js
+     * const schema = User.getCreateValidation();
+     * const validated = await schema.validate(data);
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#validation}
+     */
+    getCreateValidation(options?: any): any;
+
+    /**
+     * Returns a validation schema for updating existing documents.
+     *
+     * @param {Object} [options] - Configuration options
+     *
+     * | | | |
+     * |---|---|---|
+     * | `allowNull` | `boolean` | Allow null values to unset fields (default: true) |
+     * | `applyUnique` | `boolean` | Apply unique field validation (default: true) |
+     * | `skipRequired` | `boolean` | Skip required field checks (default: true) |
+     * | `stripUnknown` | `boolean` | Strip unknown fields (default: true) |
+     * | `stripDeleted` | `boolean` | Strip deleted fields from schema (default: true) |
+     * | `allowFlatKeys` | `boolean` | Allow dot notation for updates (default: true) |
+     * | `allowIncludes` | `boolean` | Allow include parameter (default: false) |
+     * | `stripTimestamps` | `boolean` | Strip createdAt/updatedAt fields (default: true) |
+     * | `allowExpandedRefs` | `boolean` | Allow expanded object references (default: true) |
+     * | `requireWriteAccess` | `boolean` | Require write access validation (default: true) |
+     *
+     * @returns {Object} - Yada validation schema
+     *
+     * @example
+     * ```js
+     * const schema = User.getUpdateValidation();
+     * const validated = await schema.validate(updates);
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#validation}
+     */
+    getUpdateValidation(options?: any): any;
+
+    /**
+     * Returns a validation schema for search queries.
+     *
+     * @param {Object} [options] - Configuration options
+     *
+     * | | | |
+     * |---|---|---|
+     * | `allowExport` | `boolean` | Include export validation (filename, format) |
+     * | `defaults` | `Object` | Default values for search parameters |
+     * | `formats` | `Object` | Custom export formats configuration |
+     *
+     * @returns {Object} - Yada validation schema
+     *
+     * @example
+     * ```js
+     * const schema = User.getSearchValidation({
+     *   allowExport: true
+     * });
+     * const validated = await schema.validate(query);
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#validation}
+     */
+    getSearchValidation(options?: any): any;
+
+    /**
+     * Returns a validation schema for delete operations.
+     *
+     * @returns {Object} - Yada validation schema
+     *
+     * @example
+     * ```js
+     * const schema = User.getDeleteValidation();
+     * await schema.validate({ authUser, document });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#validation}
+     */
+    getDeleteValidation(): any;
+
+    /**
+     * Returns the validation schema for include fields.
+     *
+     * @returns {Object} - Yada validation schema for include parameter
+     *
+     * @example
+     * ```js
+     * const schema = User.getIncludeValidation();
+     * const validated = await schema.validate(['organization', 'createdBy']);
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#validation}
+     */
+    getIncludeValidation(): any;
+
+    /**
+     * Returns a base validation schema with deleted fields stripped and read access required.
+     *
+     * @returns {Object} - Yada validation schema
+     *
+     * @example
+     * ```js
+     * const schema = User.getBaseSchema();
+     * const validated = await schema.validate(data);
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#validation}
+     */
+    getBaseSchema(): any;
+  }
+}

package/types/access.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.js"],"names":[],"mappings":"AAIA;;GAEG;AACH,oCAFW,MAAM,GAAC,MAAM,EAAE,yBA2BzB"}

package/types/const.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../src/const.js"],"names":[],"mappings":";;;;;;;;AASA,iCAAkC,CAAC,CAAC"}

package/types/delete-hooks.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"delete-hooks.d.ts","sourceRoot":"","sources":["../src/delete-hooks.js"],"names":[],"mappings":"AASA,wDAgBC;AAED,qEAqCC"}

package/types/env.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.js"],"names":[],"mappings":"AAAA,4BAAyC"}

package/types/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.js"],"names":[],"mappings":"AAAA;CAA8C;AAE9C;IACE,uBAGC;IADC,UAAgB;CAEnB;AAED;IACE,wCAGC;IADC,aAAsB;CAEzB;AAED;IACE,wCAGC;IADC,aAAsB;IAGxB;;;MAKC;CACF"}

package/types/include.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"include.d.ts","sourceRoot":"","sources":["../src/include.js"],"names":[],"mappings":"AAkBA,gDAuEC;AAMD,uDA4BC;AAGD,yDAIC;AAaD,yEAUC"}

package/types/load.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.js"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,sCAJW,MAAM,QACN,MAAM,OAahB;AAED;;;;GAIG;AACH,sCAFW,MAAM,mBAkBhB;qBA3CoB,UAAU"}

package/types/references.d.ts

@@ -1,2 +0,0 @@
-export function applyReferences(schema: any): void;
-//# sourceMappingURL=references.d.ts.map

package/types/references.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.js"],"names":[],"mappings":"AAMA,mDAoDC"}