monorise 1.1.0-dev.0 → 1.1.0-dev.1

package/dist/base/index.d.ts

@@ -29,6 +29,25 @@ declare enum Entity {
 interface EntitySchemaMap {
     [key: string]: Record<string, any>;
 }
+/**
+ * @description Configuration for a mutual relationship between two entities.
+ * Defines the schema for mutualData validation. Define once, reference from both entity configs.
+ *
+ * @example
+ * ```ts
+ * const enrollmentMutual = createMutualConfig({
+ *   entities: [Entity.STUDENT, Entity.COURSE],
+ *   mutualDataSchema: z.object({
+ *     role: z.enum(['student', 'auditor']),
+ *     enrolledAt: z.string().datetime(),
+ *   }),
+ * });
+ * ```
+ */
+interface MutualConfig<MD extends z.ZodRawShape = z.ZodRawShape> {
+    entities: [Entity, Entity];
+    mutualDataSchema: z.ZodObject<MD>;
+}
 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;
@@ -133,6 +152,11 @@ interface MonoriseEntityConfig<T extends Entity = Entity, B extends z.ZodRawShap
                  * @returns the final state of `mutualData` to be stored in the mutual record. Must be an object.
                  */
                 mutualDataProcessor?: (mutualIds: string[], currentMutual: any, customContext?: Record<string, any>) => Record<string, any>;
+                /**
+                 * @description (Optional) Reference to a mutual config created by `createMutualConfig`.
+                 * Provides mutualData schema validation for create/update operations on this mutual relationship.
+                 */
+                mutual?: MutualConfig;
             };
         };
         /**
@@ -353,6 +377,7 @@ declare const createEntityConfig: <T extends Entity, B extends z.ZodRawShape, C
                 entityType: Entity;
                 toMutualIds?: (context: any) => string[];
                 mutualDataProcessor?: (mutualIds: string[], currentMutual: any, customContext?: Record<string, any>) => Record<string, any>;
+                mutual?: MutualConfig;
             };
         };
         prejoins?: {
@@ -394,5 +419,6 @@ declare const createEntityConfig: <T extends Entity, B extends z.ZodRawShape, C
         [conditionName: string]: undefined | ((data: Partial<z.objectUtil.addQuestionMarks<z.baseObjectOutputType<B>, any> extends infer T_35 ? { [k_6 in keyof T_35]: T_35[k_6]; } : never>) => undefined);
     } | undefined;
 };
+declare const createMutualConfig: <MD extends z.ZodRawShape>(config: MutualConfig<MD>) => MutualConfig<MD>;
 
-export { type AdjustmentCondition, type AdjustmentConditionFn, type CreatedEntity, type DraftEntity, Entity, type EntitySchemaMap, type MonoriseEntityConfig, type NumericFields, type UpdateCondition, type UpdateConditionFn, type WhereClause, type WhereConditions, type WhereOperator, createEntityConfig };
+export { type AdjustmentCondition, type AdjustmentConditionFn, type CreatedEntity, type DraftEntity, Entity, type EntitySchemaMap, type MonoriseEntityConfig, type MutualConfig, type NumericFields, type UpdateCondition, type UpdateConditionFn, type WhereClause, type WhereConditions, type WhereOperator, createEntityConfig, createMutualConfig };

package/dist/base/index.js

@@ -37,8 +37,10 @@ function makeSchema(config) {
 var createEntityConfig = (config) => __spreadProps(__spreadValues({}, config), {
   finalSchema: makeSchema(config)
 });
+var createMutualConfig = (config) => config;
 export {
   Entity,
-  createEntityConfig
+  createEntityConfig,
+  createMutualConfig
 };
 //# sourceMappingURL=index.js.map

package/dist/base/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../types/monorise.type.ts","../utils/index.ts"],"sourcesContent":["import type { z } from 'zod';\nimport type { WhereConditions } from './conditions.type';\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   * @deprecated Use `conditions` instead. Will be removed in a future version.\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      } extends never ? string : 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      } extends never ? string : keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n    };\n  };\n\n  /**\n   * @description Named conditions for adjustEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data, adjustments) => WhereConditions` that receives the entity's current data\n   * and the adjustment deltas.\n   *\n   * When defined, `$condition` is **required** in the adjustEntity request body.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression.\n   *\n   * @example\n   * ```ts\n   * {\n   *   adjustmentConditions: {\n   *     withdraw: (data, adjustments) => ({\n   *       balance: { $gte: (data.minBalance ?? 0) + Math.abs(adjustments?.balance ?? 0) },\n   *     }),\n   *     deposit: (data, adjustments) => ({\n   *       balance: { $lte: 1000000 - (adjustments.balance ?? 0) },\n   *     }),\n   *   }\n   * }\n   * ```\n   */\n  adjustmentConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((\n          data: Partial<z.infer<z.ZodObject<B>>>,\n          adjustments: Record<string, number>,\n        ) => WhereConditions);\n  };\n\n  /**\n   * @description Named conditions for updateEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data) => WhereConditions` that receives the entity's current data.\n   *\n   * `$condition` is always **optional** for updateEntity.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression. Replaces raw `$where` (deprecated).\n   *\n   * @example\n   * ```ts\n   * {\n   *   updateConditions: {\n   *     publish: { status: { $eq: 'draft' } },\n   *     archive: (data) => ({ status: { $ne: 'archived' } }),\n   *   }\n   * }\n   * ```\n   */\n  updateConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((data: Partial<z.infer<z.ZodObject<B>>>) => WhereConditions);\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<B & CO['shape'] & MO['shape']>\n      : z.ZodObject<B & CO['shape']>\n    : MO extends z.AnyZodObject\n      ? z.ZodObject<B & MO['shape']>\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":";;;;;;;;;;;;;;;;;;;;;AAGO,IAAK,SAAL,kBAAKA,YAAL;AAAK,SAAAA;AAAA,GAAA;;;ACFZ,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';\nimport type { WhereConditions } from './conditions.type';\n\nexport enum Entity {}\n\nexport interface EntitySchemaMap {\n  [key: string]: Record<string, any>;\n}\n\n/**\n * @description Configuration for a mutual relationship between two entities.\n * Defines the schema for mutualData validation. Define once, reference from both entity configs.\n *\n * @example\n * ```ts\n * const enrollmentMutual = createMutualConfig({\n *   entities: [Entity.STUDENT, Entity.COURSE],\n *   mutualDataSchema: z.object({\n *     role: z.enum(['student', 'auditor']),\n *     enrolledAt: z.string().datetime(),\n *   }),\n * });\n * ```\n */\nexport interface MutualConfig<\n  MD extends z.ZodRawShape = z.ZodRawShape,\n> {\n  entities: [Entity, Entity];\n  mutualDataSchema: z.ZodObject<MD>;\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         * @description (Optional) Reference to a mutual config created by `createMutualConfig`.\n         * Provides mutualData schema validation for create/update operations on this mutual relationship.\n         */\n        mutual?: MutualConfig;\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   * @deprecated Use `conditions` instead. Will be removed in a future version.\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      } extends never ? string : 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      } extends never ? string : keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n    };\n  };\n\n  /**\n   * @description Named conditions for adjustEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data, adjustments) => WhereConditions` that receives the entity's current data\n   * and the adjustment deltas.\n   *\n   * When defined, `$condition` is **required** in the adjustEntity request body.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression.\n   *\n   * @example\n   * ```ts\n   * {\n   *   adjustmentConditions: {\n   *     withdraw: (data, adjustments) => ({\n   *       balance: { $gte: (data.minBalance ?? 0) + Math.abs(adjustments?.balance ?? 0) },\n   *     }),\n   *     deposit: (data, adjustments) => ({\n   *       balance: { $lte: 1000000 - (adjustments.balance ?? 0) },\n   *     }),\n   *   }\n   * }\n   * ```\n   */\n  adjustmentConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((\n          data: Partial<z.infer<z.ZodObject<B>>>,\n          adjustments: Record<string, number>,\n        ) => WhereConditions);\n  };\n\n  /**\n   * @description Named conditions for updateEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data) => WhereConditions` that receives the entity's current data.\n   *\n   * `$condition` is always **optional** for updateEntity.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression. Replaces raw `$where` (deprecated).\n   *\n   * @example\n   * ```ts\n   * {\n   *   updateConditions: {\n   *     publish: { status: { $eq: 'draft' } },\n   *     archive: (data) => ({ status: { $ne: 'archived' } }),\n   *   }\n   * }\n   * ```\n   */\n  updateConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((data: Partial<z.infer<z.ZodObject<B>>>) => WhereConditions);\n  };\n}\n","import type { Entity, MonoriseEntityConfig, MutualConfig } 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<B & CO['shape'] & MO['shape']>\n      : z.ZodObject<B & CO['shape']>\n    : MO extends z.AnyZodObject\n      ? z.ZodObject<B & MO['shape']>\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\nconst createMutualConfig = <MD extends z.ZodRawShape>(\n  config: MutualConfig<MD>,\n) => config;\n\nexport { createEntityConfig, createMutualConfig };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAGO,IAAK,SAAL,kBAAKA,YAAL;AAAK,SAAAA;AAAA,GAAA;;;ACFZ,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;AAEA,IAAM,qBAAqB,CACzB,WACG;","names":["Entity"]}

package/dist/core/index.d.ts

@@ -4608,12 +4608,14 @@ declare class UpsertEntityController {
 }
 
 declare class MutualService {
+    private EntityConfig;
     private entityRepository;
     private mutualRepository;
     private publishEvent;
     private ddbUtils;
     private entityServiceLifeCycle;
-    constructor(entityRepository: EntityRepository, mutualRepository: MutualRepository, publishEvent: typeof publishEvent, ddbUtils: DbUtils, entityServiceLifeCycle: EntityServiceLifeCycle);
+    constructor(EntityConfig: Record<Entity$2, ReturnType<typeof createEntityConfig>>, entityRepository: EntityRepository, mutualRepository: MutualRepository, publishEvent: typeof publishEvent, ddbUtils: DbUtils, entityServiceLifeCycle: EntityServiceLifeCycle);
+    private getMutualDataSchema;
     createMutual: <B extends Entity$2, T extends Entity$2, A extends Entity$2>({ byEntityType, byEntityId, entityType, entityId, mutualPayload, accountId, options, }: {
         byEntityType: B;
         byEntityId: string;
@@ -4632,13 +4634,17 @@ declare class MutualService {
             ExpressionAttributeValues?: Record<string, AttributeValue>;
         };
     }) => Promise<{
-        mutual: Mutual<B, T, Record<string, any>>;
+        mutual: Mutual<B, T, {
+            [x: string]: any;
+        }>;
         eventPayload: {
             byEntityType: B;
             byEntityId: string;
             entityType: T;
             entityId: string;
-            parsedMutualPayload: Record<string, any>;
+            parsedMutualPayload: {
+                [x: string]: any;
+            };
             accountId: string | string[] | undefined;
             publishedAt: string;
         };

package/dist/core/index.js

@@ -2315,7 +2315,7 @@ var handler2 = (container) => (ev) => __async(null, null, function* () {
   const { entityRepository, mutualRepository, publishEvent: publishEvent2 } = container;
   yield Promise.allSettled(
     ev.Records.map((record) => __async(null, null, function* () {
-      var _a, _b, _c, _d;
+      var _a, _b, _c, _d, _e;
       const errorContext = {};
       const body = parseSQSBusEvent(record.body);
       const { detail } = body;
@@ -2338,6 +2338,7 @@ var handler2 = (container) => (ev) => __async(null, null, function* () {
           );
         }
         const mutualDataProcessor = (_d = config.mutualDataProcessor) != null ? _d : (() => ({}));
+        const mutualDataSchema = (_e = config.mutual) == null ? void 0 : _e.mutualDataSchema;
         yield mutualRepository.createMutualLock({
           byEntityType,
           byEntityId,
@@ -2373,6 +2374,20 @@ var handler2 = (container) => (ev) => __async(null, null, function* () {
           addedEntityIds,
           (id) => __async(null, null, function* () {
             const entity = yield entityRepository.getEntity(entityType, id);
+            const processedMutualData = mutualDataProcessor(
+              mutualIds,
+              new Mutual(
+                byEntityType,
+                byEntityId,
+                byEntity.data,
+                entityType,
+                id,
+                entity.data,
+                {}
+              ),
+              customContext
+            );
+            const parsedMutualData = mutualDataSchema ? mutualDataSchema.parse(processedMutualData) : processedMutualData;
             yield mutualRepository.createMutual(
               byEntityType,
               byEntityId,
@@ -2380,19 +2395,7 @@ var handler2 = (container) => (ev) => __async(null, null, function* () {
               entityType,
               id,
               entity.data,
-              mutualDataProcessor(
-                mutualIds,
-                new Mutual(
-                  byEntityType,
-                  byEntityId,
-                  byEntity.data,
-                  entityType,
-                  id,
-                  entity.data,
-                  {}
-                ),
-                customContext
-              ),
+              parsedMutualData,
               {
                 ConditionExpression: "attribute_not_exists(#mutualUpdatedAt) OR #mutualUpdatedAt < :publishedAt",
                 ExpressionAttributeNames: {
@@ -2429,25 +2432,27 @@ var handler2 = (container) => (ev) => __async(null, null, function* () {
         const updateEntities = yield processEntities(
           toUpdateEntityIds,
           (id) => __async(null, null, function* () {
+            const processedMutualData = mutualDataProcessor(
+              mutualIds,
+              new Mutual(
+                byEntityType,
+                byEntityId,
+                byEntity.data,
+                entityType,
+                id,
+                {},
+                {}
+              ),
+              customContext
+            );
+            const parsedMutualData = mutualDataSchema ? mutualDataSchema.parse(processedMutualData) : processedMutualData;
             yield mutualRepository.updateMutual(
               byEntityType,
               byEntityId,
               entityType,
               id,
               {
-                mutualData: mutualDataProcessor(
-                  mutualIds,
-                  new Mutual(
-                    byEntityType,
-                    byEntityId,
-                    byEntity.data,
-                    entityType,
-                    id,
-                    {},
-                    {}
-                  ),
-                  customContext
-                ),
+                mutualData: parsedMutualData,
                 mutualUpdatedAt: publishedAt
               },
               {
@@ -8510,7 +8515,8 @@ var EntityService = class {
 // services/mutual.service.ts
 import { ulid as ulid4 } from "ulid";
 var MutualService = class {
-  constructor(entityRepository, mutualRepository, publishEvent2, ddbUtils, entityServiceLifeCycle) {
+  constructor(EntityConfig, entityRepository, mutualRepository, publishEvent2, ddbUtils, entityServiceLifeCycle) {
+    this.EntityConfig = EntityConfig;
     this.entityRepository = entityRepository;
     this.mutualRepository = mutualRepository;
     this.publishEvent = publishEvent2;
@@ -8525,6 +8531,7 @@ var MutualService = class {
       accountId,
       options = {}
     }) {
+      var _a;
       const {
         ensureEntityStrongConsistentWrite = false,
         asEntity,
@@ -8545,7 +8552,7 @@ var MutualService = class {
           options
         }
       };
-      const schema = external_exports.record(external_exports.string(), external_exports.any());
+      const schema = (_a = this.getMutualDataSchema(byEntityType, entityType)) != null ? _a : external_exports.record(external_exports.string(), external_exports.any());
       const parsedMutualPayload = schema.parse(mutualPayload);
       const [{ data: byEntityData }, { data: entityData }] = yield Promise.all([
         this.entityRepository.getEntity(byEntityType, byEntityId),
@@ -8648,7 +8655,8 @@ var MutualService = class {
       accountId,
       options
     }) {
-      const schema = external_exports.record(external_exports.string(), external_exports.any());
+      var _a;
+      const schema = (_a = this.getMutualDataSchema(byEntityType, entityType)) != null ? _a : external_exports.record(external_exports.string(), external_exports.any());
       const parsedMutualPayload = schema.parse(mutualPayload);
       const mutual = yield this.mutualRepository.updateMutual(
         byEntityType,
@@ -8697,6 +8705,22 @@ var MutualService = class {
       return mutual;
     });
   }
+  getMutualDataSchema(byEntityType, entityType) {
+    var _a, _b, _c;
+    for (const [from, to] of [
+      [byEntityType, entityType],
+      [entityType, byEntityType]
+    ]) {
+      const mutualFields = (_b = (_a = this.EntityConfig[from]) == null ? void 0 : _a.mutual) == null ? void 0 : _b.mutualFields;
+      if (!mutualFields) continue;
+      for (const config of Object.values(mutualFields)) {
+        if (config.entityType === to && ((_c = config.mutual) == null ? void 0 : _c.mutualDataSchema)) {
+          return config.mutual.mutualDataSchema;
+        }
+      }
+    }
+    return void 0;
+  }
 };
 
 // controllers/tag/list-tags.controller.ts
@@ -9395,6 +9419,7 @@ var DependencyContainer = class {
   get mutualService() {
     return this.createCachedInstance(
       MutualService,
+      this.config.EntityConfig,
       this.entityRepository,
       this.mutualRepository,
       this.publishEvent,