@bedrockio/model 0.19.3 → 0.20.0

package/types/modules/include.d.ts

@@ -0,0 +1,92 @@
+import type { HydratedDocument } from 'mongoose';
+
+declare module 'mongoose' {
+  interface Model<
+    TRawDocType,
+    TQueryHelpers = {},
+    TInstanceMethods = {},
+    TVirtuals = {},
+    THydratedDocumentType = HydratedDocument<
+      TRawDocType,
+      TVirtuals & TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals
+    >,
+    TSchema = any,
+  > {
+    /**
+     * Creates a document and then populates related fields specified in the include parameter.
+     *
+     * @param {Object} attributes - Document attributes including optional include property
+     *
+     * | | | |
+     * |---|---|---|
+     * | `include` | `string\|string[]\|Set` | Fields to populate after creation |
+     *
+     * @returns {Promise<Document>} - The created and populated document
+     *
+     * @example
+     * ```js
+     * const user = await User.createWithInclude({
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     *   organizationId: '507f1f77bcf86cd799439011',
+     *   include: ['organization']
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#includes}
+     */
+    createWithInclude(attributes: any): Promise<any>;
+  }
+
+  interface Document {
+    /**
+     * Populates related fields on this document and stores select parameters for serialization.
+     *
+     * @param {string|string[]|Set} include - Fields to populate
+     * @param {Object} [options] - Options
+     *
+     * | | | |
+     * |---|---|---|
+     * | `force` | `boolean` | Force re-population of already populated fields |
+     *
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```js
+     * await user.include(['organization', 'createdBy']);
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#includes}
+     */
+    include(
+      include: string | string[] | Set<string>,
+      options?: any,
+    ): Promise<void>;
+
+    /**
+     * Assigns attributes to this document and stores include parameters in $locals for later population.
+     *
+     * @param {Object} attributes - Document attributes including optional include property
+     *
+     * | | | |
+     * |---|---|---|
+     * | `include` | `string\|string[]\|Set` | Fields to populate after save |
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```js
+     * user.assignWithInclude({
+     *   name: 'Jane Doe',
+     *   include: ['organization']
+     * });
+     * await user.save();
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#includes}
+     */
+    assignWithInclude(attributes: any): void;
+  }
+}

package/types/modules/reload.d.ts

@@ -0,0 +1,17 @@
+declare module 'mongoose' {
+  interface Document {
+    /**
+     * Reloads this document from the database, preserving populated paths and virtual references.
+     *
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```js
+     * await user.reload();
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#reload}
+     */
+    reload(): Promise<void>;
+  }
+}

package/types/modules/search.d.ts

@@ -0,0 +1,137 @@
+import type { HydratedDocument } from 'mongoose';
+
+declare module 'mongoose' {
+  interface Model<
+    TRawDocType,
+    TQueryHelpers = {},
+    TInstanceMethods = {},
+    TVirtuals = {},
+    THydratedDocumentType = HydratedDocument<
+      TRawDocType,
+      TVirtuals & TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals
+    >,
+    TSchema = any,
+  > {
+    /**
+     * Performs a search query with pagination and filtering.
+     *
+     * @param {Object} options
+     *
+     * | | | |
+     * |---|---|---|
+     * | `ids` | `string[]` | Array of IDs to filter by |
+     * | `keyword` | `string` | Keyword for text search across specified fields |
+     * | `skip` | `number` | Number of records to skip (for pagination) |
+     * | `limit` | `number` | Maximum number of records to return |
+     * | `sort` | `Object\|Object[]` | Sort order specification |
+     * | `sort.field` | `string` | Field name to sort by |
+     * | `sort.order` | `'asc'\|'desc'` | Sort direction |
+     *
+     * @returns {Promise}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `data` | `Array` | Array of matching documents |
+     * | `meta` | `Object` | Metadata about the search results |
+     * | `meta.total` | `number` | Total number of matching documents |
+     * | `meta.skip` | `number` | Number of records skipped |
+     * | `meta.limit` | `number` | Maximum number of records returned |
+     *
+     * @example
+     * ```js
+     * // Basic search
+     * const results = await User.search({
+     *   keyword: 'john',
+     *   limit: 10,
+     *   skip: 0,
+     *   sort: {
+     *     field: 'createdAt',
+     *     order: 'desc'
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#search}
+     */
+    search(options: SearchOptions): Promise<SearchResult>;
+    /**
+     * Performs a search using an aggregation pipeline.
+     *
+     * @param {Array} pipeline - MongoDB aggregation pipeline stages
+     * @param {Object} [options]
+     *
+     * | | | |
+     * |---|---|---|
+     * | `skip` | `number` | Number of records to skip (for pagination) |
+     * | `limit` | `number` | Maximum number of records to return |
+     * | `sort` | `Object\|Object[]` | Sort order specification |
+     * | `sort.field` | `string` | Field name to sort by |
+     * | `sort.order` | `'asc'\|'desc'` | Sort direction |
+     *
+     * @returns {Promise}
+     *
+     * | | | |
+     * |---|---|---|
+     * | `data` | `Array` | Array of matching documents |
+     * | `meta` | `Object` | Metadata about the search results |
+     * | `meta.total` | `number` | Total number of matching documents |
+     * | `meta.skip` | `number` | Number of records skipped |
+     * | `meta.limit` | `number` | Maximum number of records returned |
+     *
+     * @example
+     * ```js
+     * // Pipeline search
+     * const results = await User.search(
+     *   [
+     *     {
+     *       $match: {
+     *         active: true
+     *       }
+     *     }
+     *   ],
+     *   {
+     *     limit: 20
+     *   }
+     * );
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#search}
+     */
+    search(
+      pipeline: any[],
+      options?: SearchPipelineOptions,
+    ): Promise<SearchResult>;
+  }
+}
+
+type SortOption = {
+  field: string;
+  order: 'asc' | 'desc';
+};
+
+type SearchOptions = {
+  ids?: string[];
+  keyword?: string;
+  skip?: number;
+  limit?: number;
+  sort?: SortOption | SortOption[];
+};
+
+type SearchPipelineOptions = {
+  skip?: number;
+  limit?: number;
+  sort?: SortOption | SortOption[];
+};
+
+type SearchResultMeta = {
+  total: number;
+  skip: number;
+  limit: number;
+};
+
+type SearchResult = {
+  data: any[];
+  meta: SearchResultMeta;
+};

package/types/modules/slug.d.ts

@@ -0,0 +1,80 @@
+import type { HydratedDocument } from 'mongoose';
+
+declare module 'mongoose' {
+  interface Model<
+    TRawDocType,
+    TQueryHelpers = {},
+    TInstanceMethods = {},
+    TVirtuals = {},
+    THydratedDocumentType = HydratedDocument<
+      TRawDocType,
+      TVirtuals & TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals
+    >,
+    TSchema = any,
+  > {
+    /**
+     * Finds a document by either its ObjectId or slug field. Automatically detects if the string is a valid 24-character ObjectId.
+     *
+     * @param {string} str - Either an ObjectId or a slug
+     * @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.findByIdOrSlug('john-doe');
+     * const sameUser = await User.findByIdOrSlug('507f1f77bcf86cd799439011');
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#slugs}
+     */
+    findByIdOrSlug(str: string, projection?: any, options?: any): Promise<any>;
+
+    /**
+     * Finds a soft-deleted document by either its ObjectId or slug field.
+     *
+     * @param {string} str - Either an ObjectId or a slug
+     * @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.findByIdOrSlugDeleted('john-doe');
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#slugs}
+     */
+    findByIdOrSlugDeleted(
+      str: string,
+      projection?: any,
+      options?: any,
+    ): Promise<any>;
+
+    /**
+     * Finds a document (deleted or not) by either its ObjectId or slug field.
+     *
+     * @param {string} str - Either an ObjectId or a slug
+     * @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.findByIdOrSlugWithDeleted('john-doe');
+     * ```
+     *
+     * @see {@link https://github.com/bedrockio/model#slugs}
+     */
+    findByIdOrSlugWithDeleted(
+      str: string,
+      projection?: any,
+      options?: any,
+    ): Promise<any>;
+  }
+}