@monorise/base 3.0.2-dev.0 → 3.1.0

package/dist/index.d.ts

@@ -6,6 +6,9 @@ interface EntitySchemaMap {
     [key: string]: Record<string, any>;
 }
 type DraftEntity<T extends Entity = Entity> = T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;
+type NumericFields<T> = {
+    [K in keyof T as T[K] extends number ? K : never]?: number;
+};
 type CreatedEntity<T extends Entity = Entity> = {
     entityId: string;
     entityType: string;
@@ -202,7 +205,7 @@ interface MonoriseEntityConfig<T extends Entity = Entity, B extends z.ZodRawShap
         processor: (entity: {
             entityId: string;
             entityType: string;
-            data: z.infer<z.ZodObject<B>>;
+            data: Record<string, any>;
             createdAt: string;
             updatedAt: string;
         }) => {
@@ -210,10 +213,46 @@ interface MonoriseEntityConfig<T extends Entity = Entity, B extends z.ZodRawShap
             sortValue?: string;
         }[];
     }[];
+    /**
+     * @description (Optional) Constraints for `adjustEntity` operations.
+     * When adjusting numeric fields, these constraints are enforced at the database level.
+     * If an adjustment would violate a constraint, the operation is rejected.
+     *
+     * @example
+     * ```ts
+     * {
+     *   adjustmentConstraints: {
+     *     // Static: same for all entities of this type
+     *     balance: { min: 0 },
+     *     credits: { min: 0, max: 10000 },
+     *
+     *     // Dynamic: reads constraint value from entity's own data
+     *     balance: { minField: 'minBalance' },
+     *     credits: { min: 0, maxField: 'creditLimit' },
+     *   }
+     * }
+     * ```
+     */
+    adjustmentConstraints?: {
+        [fieldName: string]: {
+            /** Static minimum value */
+            min?: number;
+            /** Static maximum value */
+            max?: number;
+            /** Field name on the entity whose value is used as the minimum (must be a numeric field) */
+            minField?: keyof {
+                [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;
+            };
+            /** Field name on the entity whose value is used as the maximum (must be a numeric field) */
+            maxField?: keyof {
+                [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;
+            };
+        };
+    };
 }
 
 declare const createEntityConfig: <T extends Entity, B extends z.ZodRawShape, C extends z.ZodRawShape, M extends z.ZodRawShape, CO extends z.ZodObject<C> | undefined = undefined, MO extends z.ZodObject<M> | undefined = undefined>(config: MonoriseEntityConfig<T, B, C, M, CO, MO>) => {
-    finalSchema: (CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_1 ? { [k in keyof T_1]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any>[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_2 ? { [k_1 in keyof T_2]: z.baseObjectInputType<MO["shape"] & CO["shape"]>[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_3 ? { [k_2 in keyof T_3]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any>[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_4 ? { [k_3 in keyof T_4]: z.baseObjectInputType<MO["shape"] & B>[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_5 ? { [k_4 in keyof T_5]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any>[k_4]; } : never, z.baseObjectInputType<B> extends infer T_6 ? { [k_5 in keyof T_6]: z.baseObjectInputType<B>[k_5]; } : never>) | z.ZodEffects<CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_7 ? { [k in keyof T_7]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any>[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_8 ? { [k_1 in keyof T_8]: z.baseObjectInputType<MO["shape"] & CO["shape"]>[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_9 ? { [k_2 in keyof T_9]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any>[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_10 ? { [k_3 in keyof T_10]: z.baseObjectInputType<MO["shape"] & B>[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_11 ? { [k_4 in keyof T_11]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any>[k_4]; } : never, z.baseObjectInputType<B> extends infer T_12 ? { [k_5 in keyof T_12]: z.baseObjectInputType<B>[k_5]; } : never>, z.output<CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_13 ? { [k in keyof T_13]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any>[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_14 ? { [k_1 in keyof T_14]: z.baseObjectInputType<MO["shape"] & CO["shape"]>[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_15 ? { [k_2 in keyof T_15]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any>[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_16 ? { [k_3 in keyof T_16]: z.baseObjectInputType<MO["shape"] & B>[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_17 ? { [k_4 in keyof T_17]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any>[k_4]; } : never, z.baseObjectInputType<B> extends infer T_18 ? { [k_5 in keyof T_18]: z.baseObjectInputType<B>[k_5]; } : never>>, z.input<CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_19 ? { [k in keyof T_19]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any>[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_20 ? { [k_1 in keyof T_20]: z.baseObjectInputType<MO["shape"] & CO["shape"]>[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_21 ? { [k_2 in keyof T_21]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any>[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_22 ? { [k_3 in keyof T_22]: z.baseObjectInputType<MO["shape"] & B>[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_23 ? { [k_4 in keyof T_23]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any>[k_4]; } : never, z.baseObjectInputType<B> extends infer T_24 ? { [k_5 in keyof T_24]: z.baseObjectInputType<B>[k_5]; } : never>>>;
+    finalSchema: (CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_3 ? { [k_2 in keyof T_3]: T_3[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_4 ? { [k_3 in keyof T_4]: T_4[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_5 ? { [k_4 in keyof T_5]: T_5[k_4]; } : never, z.baseObjectInputType<B> extends infer T_6 ? { [k_5 in keyof T_6]: T_6[k_5]; } : never>) | z.ZodEffects<CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_7 ? { [k in keyof T_7]: T_7[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_8 ? { [k_1 in keyof T_8]: T_8[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_9 ? { [k_2 in keyof T_9]: T_9[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_10 ? { [k_3 in keyof T_10]: T_10[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_11 ? { [k_4 in keyof T_11]: T_11[k_4]; } : never, z.baseObjectInputType<B> extends infer T_12 ? { [k_5 in keyof T_12]: T_12[k_5]; } : never>, z.output<CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_13 ? { [k in keyof T_13]: T_13[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_14 ? { [k_1 in keyof T_14]: T_14[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_15 ? { [k_2 in keyof T_15]: T_15[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_16 ? { [k_3 in keyof T_16]: T_16[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_17 ? { [k_4 in keyof T_17]: T_17[k_4]; } : never, z.baseObjectInputType<B> extends infer T_18 ? { [k_5 in keyof T_18]: T_18[k_5]; } : never>>, z.input<CO extends z.AnyZodObject ? MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & CO["shape"], z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & CO["shape"]>, any> extends infer T_19 ? { [k in keyof T_19]: T_19[k]; } : never, z.baseObjectInputType<MO["shape"] & CO["shape"]> extends infer T_20 ? { [k_1 in keyof T_20]: T_20[k_1]; } : never> : CO : MO extends z.AnyZodObject ? z.ZodObject<MO["shape"] & B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<MO["shape"] & B>, any> extends infer T_21 ? { [k_2 in keyof T_21]: T_21[k_2]; } : never, z.baseObjectInputType<MO["shape"] & B> extends infer T_22 ? { [k_3 in keyof T_22]: T_22[k_3]; } : never> : z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_23 ? { [k_4 in keyof T_23]: T_23[k_4]; } : never, z.baseObjectInputType<B> extends infer T_24 ? { [k_5 in keyof T_24]: T_24[k_5]; } : never>>>;
     name: string | T;
     displayName: string;
     authMethod?: {
@@ -221,7 +260,7 @@ declare const createEntityConfig: <T extends Entity, B extends z.ZodRawShape, C
             tokenExpiresIn: number;
         };
     };
-    baseSchema: z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_25 ? { [k_4 in keyof T_25]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any>[k_4]; } : never, z.baseObjectInputType<B> extends infer T_26 ? { [k_5 in keyof T_26]: z.baseObjectInputType<B>[k_5]; } : never>;
+    baseSchema: z.ZodObject<B, z.UnknownKeysParam, z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_25 ? { [k_4 in keyof T_25]: T_25[k_4]; } : never, z.baseObjectInputType<B> extends infer T_26 ? { [k_5 in keyof T_26]: T_26[k_5]; } : never>;
     createSchema?: CO | undefined;
     searchableFields?: (keyof B)[] | undefined;
     uniqueFields?: (keyof B)[] | undefined;
@@ -253,14 +292,22 @@ declare const createEntityConfig: <T extends Entity, B extends z.ZodRawShape, C
         processor: (entity: {
             entityId: string;
             entityType: string;
-            data: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_27 ? { [k_4 in keyof T_27]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any>[k_4]; } : never;
+            data: Record<string, any>;
             createdAt: string;
             updatedAt: string;
         }) => {
             group?: string;
             sortValue?: string;
         }[];
-    }[] | undefined;
+    }[];
+    adjustmentConstraints?: {
+        [fieldName: string]: {
+            min?: number;
+            max?: number;
+            minField?: keyof { [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K; } | undefined;
+            maxField?: keyof { [K_1 in keyof B as B[K_1] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K_1 : never]: K_1; } | undefined;
+        };
+    } | undefined;
 };
 
-export { type CreatedEntity, type DraftEntity, Entity, type EntitySchemaMap, type MonoriseEntityConfig, createEntityConfig };
+export { type CreatedEntity, type DraftEntity, Entity, type EntitySchemaMap, type MonoriseEntityConfig, type NumericFields, createEntityConfig };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../types/monorise.type.ts","../utils/index.ts"],"sourcesContent":["import type { z } from 'zod';\n\nexport enum Entity {}\n\nexport interface EntitySchemaMap {\n  [key: string]: Record<string, any>;\n}\n\nexport type DraftEntity<T extends Entity = Entity> =\n  T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n\nexport type CreatedEntity<T extends Entity = Entity> = {\n  entityId: string;\n  entityType: string;\n  data: T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n  createdAt: string;\n  updatedAt: string;\n};\n\n/**\n * @description Configuration for a monorise entity, a shared configuration that is used across frontend and backend.\n * This can be served as a single source of truth for the entity configuration.\n * It is used to define the schema, and mutual relationships between this entity and other entities.\n *\n * @example\n * ```ts\n * const baseSchema = z.object({\n *   title: z.string(),\n * }).partial();\n *\n * const createSchema = baseSchema.extend({\n *   title: z.string(),\n * })\n *\n * const config = createEntityConfig({\n *   name: 'learner',\n *   displayName: 'Learner',\n *   baseSchema,\n *   createSchema,\n * });\n * ```\n */\nexport interface MonoriseEntityConfig<\n  T extends Entity = Entity,\n  B extends z.ZodRawShape = z.ZodRawShape,\n  C extends z.ZodRawShape = z.ZodRawShape,\n  M extends z.ZodRawShape = z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n> {\n  /**\n   * @description Name of the entity. Must be in **lower-kebab-case** and **unique** across all entities\n   *\n   * @example `learner`, `learning-activity`\n   */\n  name: string | T;\n\n  /**\n   * @description Display name of the entity. It is not required to be unique\n   */\n  displayName: string;\n\n  /**\n   * @description (DEPRECATED) Use `uniqueFields` instead, Monorise should not handle auth mechanism\n   * @description (Optional) Specify the authentication method to be used for the entity\n   */\n  authMethod?: {\n    /**\n     * @description Authentication method using email\n     *\n     * Note: The email used for authentication is unique per entity.\n     * For example, if `johndoe@mail.com` is used for `learner` entity,\n     * it can be reused again on `admin` entity. However, the same email\n     * address cannot be repeated for the same entity.\n     */\n    email: {\n      /**\n       * @description Number of milliseconds before the token expires\n       */\n      tokenExpiresIn: number;\n    };\n  };\n\n  /**\n   * @description Base schema for the entity\n   */\n  baseSchema: z.ZodObject<B>;\n\n  /**\n   * @description Minimal schema required to create an entity\n   */\n  createSchema?: CO;\n  searchableFields?: (keyof B)[];\n  uniqueFields?: (keyof B)[];\n\n  /**\n   * @description Define mutual relationship of this entity with other entities\n   */\n  mutual?: {\n    /**\n     * @description Subscribes to update events from specified entities in the array.\n     * These events will be used to run prejoin processor.\n     */\n    subscribes?: { entityType: Entity }[];\n    /**\n     * @description Virtual schema for mutual relationship. The schema is only used for validation purpose, but these fields are not stored in the database\n     */\n    mutualSchema: MO;\n\n    /**\n     * @description Keys of `mutualFields` are fields defined in `mutualSchema`.\n     * Each field is a mutual relationship between this entity and another entity.\n     */\n    mutualFields: {\n      [key: string]: {\n        entityType: Entity;\n        toMutualIds?: (context: any) => string[];\n        /**\n         * @description (Optional) Custom function to process `mutualData`. If not provided, `mutualData` will be empty.\n         *\n         * @returns the final state of `mutualData` to be stored in the mutual record. Must be an object.\n         */\n        mutualDataProcessor?: (\n          mutualIds: string[],\n          currentMutual: any,\n          customContext?: Record<string, any>,\n        ) => Record<string, any>;\n      };\n    };\n\n    /**\n     * @description (Optional) Better known as tree processor\n     * This is used to prejoin entities that are not directly related as mutual.\n     * For example, if `learner` entity is related to `course` entity, and `course` entity is related to `module` entity,\n     * prejoins can be used to join `learner` and `module` entities.\n     * With this, the `learner` entity can access the `module` entity without having to go through the `course` entity,\n     * hence reducing the number of queries.\n     *\n     * DynamoDB best practices: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-general-normalization.html\n     *\n     */\n    prejoins?: {\n      mutualField: string;\n      targetEntityType: Entity;\n      entityPaths: {\n        skipCache?: boolean;\n        entityType: Entity;\n        processor?: (items: any[], context: Record<string, any>) => any;\n      }[];\n    }[];\n  };\n  /**\n   * Use this function to perform side effects on the final schema for example refine/superRefine the schema\n   *\n   * @param schema The final schema of the entity (the combination of `baseSchema`/`createSchema` and `mutualSchema` if specified)\n   * @returns void\n   *\n   * @example\n   * ```ts\n   * effect: (schema) => {\n   *   schema.refine(\n   *     // refinement logic here\n   *   )\n   * }\n   */\n  effect?: (\n    schema: z.ZodObject<z.ZodRawShape>,\n  ) => z.ZodEffects<z.ZodObject<z.ZodRawShape>>;\n\n  /**\n   * @description (Optional) Use tags to create additional access patterns for the entity.\n   * Time complexity for retrieving tagged entities is O(1).\n   *\n   * The following configuration will create a tag named `region` for the `organization` entity grouped by `region`.\n   * You would then be able to retrieve all organizations in a specific region by:\n   * GET `/core/tag/organization/region?group={region_name}`\n   *\n   * @example\n   *\n   * ```ts\n   * {\n   *   name: 'organization',\n   *   tags: [\n   *    {\n   *      name: 'region',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            group: entity.data.region\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   *\n   * @description\n   *\n   * The following configuration will create a tag named `dob` for the `user` entity sorted by `dob`.\n   * You would then be able to retrieve all users sorted by `dob` by:\n   * GET `/core/tag/user/dob?start=2000-01-01&end=2020-12-31`\n   *\n   * @example\n   * ```ts\n   * {\n   *   name: 'user',\n   *   tags: [\n   *    {\n   *      name: 'dob',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            sortValue: entity.data.dob\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   */\n  tags?: {\n    name: string;\n    processor: (entity: {\n      entityId: string;\n      entityType: string;\n      data: z.infer<z.ZodObject<B>>;\n      createdAt: string;\n      updatedAt: string;\n    }) => {\n      group?: string;\n      sortValue?: string;\n    }[];\n  }[];\n}\n","import type { Entity, MonoriseEntityConfig } from '../types/monorise.type';\nimport { z } from 'zod';\n\nfunction makeSchema<\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(config: MonoriseEntityConfig<T, B, C, M, CO, MO>) {\n  const { baseSchema, createSchema, mutual, effect } = config;\n  const { mutualSchema } = mutual || {};\n\n  type FinalSchemaType = CO extends z.AnyZodObject\n    ? MO extends z.AnyZodObject\n      ? z.ZodObject<MO['shape'] & CO['shape']>\n      : CO\n    : MO extends z.AnyZodObject\n      ? z.ZodObject<MO['shape'] & B>\n      : z.ZodObject<B>;\n\n  const finalSchema = z.object({\n    ...baseSchema.shape,\n    ...createSchema?.shape,\n    ...mutualSchema?.shape,\n  }) as FinalSchemaType;\n\n  if (effect) {\n    return effect(finalSchema) as z.ZodEffects<FinalSchemaType>;\n  }\n\n  return finalSchema;\n}\n\nconst createEntityConfig = <\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(\n  config: MonoriseEntityConfig<T, B, C, M, CO, MO>,\n) => ({\n  ...config,\n  finalSchema: makeSchema(config),\n});\n\nexport { createEntityConfig };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAEO,IAAK,SAAL,kBAAKA,YAAL;AAAK,SAAAA;AAAA,GAAA;;;ACDZ,SAAS,SAAS;AAElB,SAAS,WAOP,QAAkD;AAClD,QAAM,EAAE,YAAY,cAAc,QAAQ,OAAO,IAAI;AACrD,QAAM,EAAE,aAAa,IAAI,UAAU,CAAC;AAUpC,QAAM,cAAc,EAAE,OAAO,iDACxB,WAAW,QACX,6CAAc,QACd,6CAAc,MAClB;AAED,MAAI,QAAQ;AACV,WAAO,OAAO,WAAW;AAAA,EAC3B;AAEA,SAAO;AACT;AAEA,IAAM,qBAAqB,CAQzB,WACI,iCACD,SADC;AAAA,EAEJ,aAAa,WAAW,MAAM;AAChC;","names":["Entity"]}
+{"version":3,"sources":["../types/monorise.type.ts","../utils/index.ts"],"sourcesContent":["import type { z } from 'zod';\n\nexport enum Entity {}\n\nexport interface EntitySchemaMap {\n  [key: string]: Record<string, any>;\n}\n\nexport type DraftEntity<T extends Entity = Entity> =\n  T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n\nexport type NumericFields<T> = {\n  [K in keyof T as T[K] extends number ? K : never]?: number;\n};\n\nexport type CreatedEntity<T extends Entity = Entity> = {\n  entityId: string;\n  entityType: string;\n  data: T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n  createdAt: string;\n  updatedAt: string;\n};\n\n/**\n * @description Configuration for a monorise entity, a shared configuration that is used across frontend and backend.\n * This can be served as a single source of truth for the entity configuration.\n * It is used to define the schema, and mutual relationships between this entity and other entities.\n *\n * @example\n * ```ts\n * const baseSchema = z.object({\n *   title: z.string(),\n * }).partial();\n *\n * const createSchema = baseSchema.extend({\n *   title: z.string(),\n * })\n *\n * const config = createEntityConfig({\n *   name: 'learner',\n *   displayName: 'Learner',\n *   baseSchema,\n *   createSchema,\n * });\n * ```\n */\nexport interface MonoriseEntityConfig<\n  T extends Entity = Entity,\n  B extends z.ZodRawShape = z.ZodRawShape,\n  C extends z.ZodRawShape = z.ZodRawShape,\n  M extends z.ZodRawShape = z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n> {\n  /**\n   * @description Name of the entity. Must be in **lower-kebab-case** and **unique** across all entities\n   *\n   * @example `learner`, `learning-activity`\n   */\n  name: string | T;\n\n  /**\n   * @description Display name of the entity. It is not required to be unique\n   */\n  displayName: string;\n\n  /**\n   * @description (DEPRECATED) Use `uniqueFields` instead, Monorise should not handle auth mechanism\n   * @description (Optional) Specify the authentication method to be used for the entity\n   */\n  authMethod?: {\n    /**\n     * @description Authentication method using email\n     *\n     * Note: The email used for authentication is unique per entity.\n     * For example, if `johndoe@mail.com` is used for `learner` entity,\n     * it can be reused again on `admin` entity. However, the same email\n     * address cannot be repeated for the same entity.\n     */\n    email: {\n      /**\n       * @description Number of milliseconds before the token expires\n       */\n      tokenExpiresIn: number;\n    };\n  };\n\n  /**\n   * @description Base schema for the entity\n   */\n  baseSchema: z.ZodObject<B>;\n\n  /**\n   * @description Minimal schema required to create an entity\n   */\n  createSchema?: CO;\n  searchableFields?: (keyof B)[];\n  uniqueFields?: (keyof B)[];\n\n  /**\n   * @description Define mutual relationship of this entity with other entities\n   */\n  mutual?: {\n    /**\n     * @description Subscribes to update events from specified entities in the array.\n     * These events will be used to run prejoin processor.\n     */\n    subscribes?: { entityType: Entity }[];\n    /**\n     * @description Virtual schema for mutual relationship. The schema is only used for validation purpose, but these fields are not stored in the database\n     */\n    mutualSchema: MO;\n\n    /**\n     * @description Keys of `mutualFields` are fields defined in `mutualSchema`.\n     * Each field is a mutual relationship between this entity and another entity.\n     */\n    mutualFields: {\n      [key: string]: {\n        entityType: Entity;\n        toMutualIds?: (context: any) => string[];\n        /**\n         * @description (Optional) Custom function to process `mutualData`. If not provided, `mutualData` will be empty.\n         *\n         * @returns the final state of `mutualData` to be stored in the mutual record. Must be an object.\n         */\n        mutualDataProcessor?: (\n          mutualIds: string[],\n          currentMutual: any,\n          customContext?: Record<string, any>,\n        ) => Record<string, any>;\n      };\n    };\n\n    /**\n     * @description (Optional) Better known as tree processor\n     * This is used to prejoin entities that are not directly related as mutual.\n     * For example, if `learner` entity is related to `course` entity, and `course` entity is related to `module` entity,\n     * prejoins can be used to join `learner` and `module` entities.\n     * With this, the `learner` entity can access the `module` entity without having to go through the `course` entity,\n     * hence reducing the number of queries.\n     *\n     * DynamoDB best practices: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-general-normalization.html\n     *\n     */\n    prejoins?: {\n      mutualField: string;\n      targetEntityType: Entity;\n      entityPaths: {\n        skipCache?: boolean;\n        entityType: Entity;\n        processor?: (items: any[], context: Record<string, any>) => any;\n      }[];\n    }[];\n  };\n  /**\n   * Use this function to perform side effects on the final schema for example refine/superRefine the schema\n   *\n   * @param schema The final schema of the entity (the combination of `baseSchema`/`createSchema` and `mutualSchema` if specified)\n   * @returns void\n   *\n   * @example\n   * ```ts\n   * effect: (schema) => {\n   *   schema.refine(\n   *     // refinement logic here\n   *   )\n   * }\n   */\n  effect?: (\n    schema: z.ZodObject<z.ZodRawShape>,\n  ) => z.ZodEffects<z.ZodObject<z.ZodRawShape>>;\n\n  /**\n   * @description (Optional) Use tags to create additional access patterns for the entity.\n   * Time complexity for retrieving tagged entities is O(1).\n   *\n   * The following configuration will create a tag named `region` for the `organization` entity grouped by `region`.\n   * You would then be able to retrieve all organizations in a specific region by:\n   * GET `/core/tag/organization/region?group={region_name}`\n   *\n   * @example\n   *\n   * ```ts\n   * {\n   *   name: 'organization',\n   *   tags: [\n   *    {\n   *      name: 'region',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            group: entity.data.region\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   *\n   * @description\n   *\n   * The following configuration will create a tag named `dob` for the `user` entity sorted by `dob`.\n   * You would then be able to retrieve all users sorted by `dob` by:\n   * GET `/core/tag/user/dob?start=2000-01-01&end=2020-12-31`\n   *\n   * @example\n   * ```ts\n   * {\n   *   name: 'user',\n   *   tags: [\n   *    {\n   *      name: 'dob',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            sortValue: entity.data.dob\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   */\n  tags?: {\n    name: string;\n    processor: (entity: { entityId: string; entityType: string; data: Record<string, any>; createdAt: string; updatedAt: string }) => {\n      group?: string;\n      sortValue?: string;\n    }[];\n  }[];\n\n  /**\n   * @description (Optional) Constraints for `adjustEntity` operations.\n   * When adjusting numeric fields, these constraints are enforced at the database level.\n   * If an adjustment would violate a constraint, the operation is rejected.\n   *\n   * @example\n   * ```ts\n   * {\n   *   adjustmentConstraints: {\n   *     // Static: same for all entities of this type\n   *     balance: { min: 0 },\n   *     credits: { min: 0, max: 10000 },\n   *\n   *     // Dynamic: reads constraint value from entity's own data\n   *     balance: { minField: 'minBalance' },\n   *     credits: { min: 0, maxField: 'creditLimit' },\n   *   }\n   * }\n   * ```\n   */\n  adjustmentConstraints?: {\n    [fieldName: string]: {\n      /** Static minimum value */\n      min?: number;\n      /** Static maximum value */\n      max?: number;\n      /** Field name on the entity whose value is used as the minimum (must be a numeric field) */\n      minField?: keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n      /** Field name on the entity whose value is used as the maximum (must be a numeric field) */\n      maxField?: keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n    };\n  };\n}\n","import type { Entity, MonoriseEntityConfig } from '../types/monorise.type';\nimport { z } from 'zod';\n\nfunction makeSchema<\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(config: MonoriseEntityConfig<T, B, C, M, CO, MO>) {\n  const { baseSchema, createSchema, mutual, effect } = config;\n  const { mutualSchema } = mutual || {};\n\n  type FinalSchemaType = CO extends z.AnyZodObject\n    ? MO extends z.AnyZodObject\n      ? z.ZodObject<MO['shape'] & CO['shape']>\n      : CO\n    : MO extends z.AnyZodObject\n      ? z.ZodObject<MO['shape'] & B>\n      : z.ZodObject<B>;\n\n  const finalSchema = z.object({\n    ...baseSchema.shape,\n    ...createSchema?.shape,\n    ...mutualSchema?.shape,\n  }) as FinalSchemaType;\n\n  if (effect) {\n    return effect(finalSchema) as z.ZodEffects<FinalSchemaType>;\n  }\n\n  return finalSchema;\n}\n\nconst createEntityConfig = <\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(\n  config: MonoriseEntityConfig<T, B, C, M, CO, MO>,\n) => ({\n  ...config,\n  finalSchema: makeSchema(config),\n});\n\nexport { createEntityConfig };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAEO,IAAK,SAAL,kBAAKA,YAAL;AAAK,SAAAA;AAAA,GAAA;;;ACDZ,SAAS,SAAS;AAElB,SAAS,WAOP,QAAkD;AAClD,QAAM,EAAE,YAAY,cAAc,QAAQ,OAAO,IAAI;AACrD,QAAM,EAAE,aAAa,IAAI,UAAU,CAAC;AAUpC,QAAM,cAAc,EAAE,OAAO,iDACxB,WAAW,QACX,6CAAc,QACd,6CAAc,MAClB;AAED,MAAI,QAAQ;AACV,WAAO,OAAO,WAAW;AAAA,EAC3B;AAEA,SAAO;AACT;AAEA,IAAM,qBAAqB,CAQzB,WACI,iCACD,SADC;AAAA,EAEJ,aAAa,WAAW,MAAM;AAChC;","names":["Entity"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monorise/base",
-  "version": "3.0.2-dev.0",
+  "version": "3.1.0",
   "description": "",
   "type": "module",
   "main": "dist/index.js",