@common-stack/store-mongo 7.1.1-alpha.8 → 7.1.1-alpha.9

package/lib/templates/repositories/dbCommonTypes.ts.template

@@ -0,0 +1,139 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file CommonTypes.ts
+ * @description Defines common types and interfaces used across the data access layer for database operations.
+ * These types are database-agnostic and can be used with any database implementation (MongoDB, PostgreSQL, etc.).
+ *
+ * Key components include:
+ * - GetAllArgs: Interface for pagination, sorting, and filtering when retrieving collections of documents
+ * - AsDomainType: Type transformer that converts database schema types to domain types
+ * - GetAllWithCountResult: Type for paginated results that include both data and total count
+ * - CreateType/UpdateType: Utility types that define the shape of data for create and update operations
+ * - FilterCriteria: Generic type for filtering data across different database implementations
+ * - ISort: Interface for defining sort operations
+ *
+ * These types ensure consistency across repositories and services, providing type safety and
+ * clear contracts for data manipulation throughout the application. They form the foundation
+ * of the data access pattern used across the entire system.
+ *
+ * @see IBaseService - Service layer that uses these types
+ * @see IBaseMongoRepository - MongoDB repository implementation using these types
+ */
+import { ISort } from 'common';
+/**
+ * Generic filter type that doesn't depend on specific database implementation
+ * Can be used for any database query operations
+ */
+export type FilterCriteria<T> = Partial<T> | Record<string, any>;
+
+/**
+ * Interface for defining sort operations
+ * Keys are field names, values are sort direction (1 for ascending, -1 for descending)
+ *
+ * @example
+ * // Sort by creation date descending, then by name ascending
+ * const sort: ISort = { createdAt: -1, name: 1 };
+ */
+/**
+ * Interface for the arguments used in getAll methods
+ *
+ * @property criteria - Filter criteria to narrow down results
+ * @property sort - Sorting configuration with field names and directions
+ * @property skip - Number of documents to skip (for pagination)
+ * @property limit - Maximum number of documents to return (for pagination)
+ * @property selectedFields - String of space-separated field names to include in the results
+ *
+ * @example
+ * // Get active users, sorted by creation date, second page with 10 items per page
+ * const options: GetAllArgs<UserSchema> = {
+ *   criteria: { active: true },
+ *   sort: { createdAt: -1 },
+ *   skip: 10,
+ *   limit: 10,
+ *   selectedFields: 'name email createdAt'
+ * };
+ */
+export interface GetAllArgs<T> {
+    criteria?: FilterCriteria<T>;
+    sort?: ISort;
+    skip?: number;
+    limit?: number;
+    selectedFields?: string;
+}
+
+/**
+ * Type transformer that converts database schema types to domain types
+ * For MongoDB, this typically means converting _id to id
+ *
+ * @example
+ * // MongoDB document
+ * type UserSchema = {
+ *   _id: ObjectId;
+ *   name: string;
+ *   email: string;
+ * };
+ *
+ * // Transformed domain object
+ * type UserDomain = AsDomainType<UserSchema>;
+ * // Equivalent to:
+ * // {
+ * //   id: string;
+ * //   name: string;
+ * //   email: string;
+ * // }
+ */
+export type AsDomainType<T> = Omit<T, '_id'> & { id: string };
+
+/**
+ * Type for paginated results that include both data and total count
+ * Used for implementing pagination UI components
+ *
+ * @property data - Array of domain objects matching the query criteria
+ * @property totalCount - Total number of documents that match the criteria (without pagination)
+ *
+ * @example
+ * const result: GetAllWithCountResult<UserSchema> = {
+ *   data: [{ id: '1', name: 'John' }, { id: '2', name: 'Jane' }],
+ *   totalCount: 50
+ * };
+ */
+export type GetAllWithCountResult<SchemaType> = {
+    data: AsDomainType<SchemaType>[];
+    totalCount: number;
+};
+
+/**
+ * Default pagination settings used throughout the application
+ * These values are used when no explicit pagination parameters are provided
+ */
+export enum PAGINATION_OPTIONS {
+    limit = 10,
+    skip = 0,
+}
+
+/**
+ * Type for create operations - omits system-generated fields
+ * This ensures that clients cannot specify fields that should be generated by the database
+ *
+ * @example
+ * // Valid create operation data
+ * const newUser: CreateType<UserSchema> = {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   role: 'user'
+ * };
+ */
+export type CreateType<SchemaType> = Omit<Partial<SchemaType>, '_id' | 'id' | 'createdAt' | 'updatedAt'>;
+
+/**
+ * Type for update operations - partial of the schema without system fields
+ * This allows for partial updates where only changed fields are specified
+ *
+ * @example
+ * // Update a user's email and role
+ * const updateData: UpdateType<UserSchema> = {
+ *   email: 'new.email@example.com',
+ *   role: 'admin'
+ * };
+ */
+export type UpdateType<SchemaType> = Partial<Omit<SchemaType, '_id'>>;

package/lib/templates/repositories/mongoCommonTypes.ts.template

@@ -0,0 +1,21 @@
+import type { Document } from 'mongoose';
+
+/**
+ * Helper type to convert a Mongoose document to a plain object
+ * Useful when working with Mongoose documents that need to be converted to domain objects
+ */
+export type AsObject<T> = T extends Document ? Omit<T, keyof Document> : T;
+
+export interface IMongoOptions {
+    collectionName?: string;
+    sessionCollectionName?: string;
+    timestamps?: {
+        createdAt: string;
+        updatedAt: string;
+    };
+    convertUserIdToMongoObjectId?: boolean;
+    convertSessionIdToMongoObjectId?: boolean;
+    caseSensitiveUserName?: boolean;
+    idProvider?: () => string | Object;
+    dateProvider?: (date?: Date) => any;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@common-stack/store-mongo",
-    "version": "7.1.1-alpha.8",
+    "version": "7.1.1-alpha.9",
     "description": "Sample core for higher packages to depend on",
     "license": "ISC",
     "author": "CDMBase LLC",
@@ -58,5 +58,5 @@
     "typescript": {
         "definition": "lib/index.d.ts"
     },
-    "gitHead": "3f3020d76d93d311d8a3c7457544557fa8ddeb77"
+    "gitHead": "54c1746625cac7261ce4df690ae05104064a0e88"
 }