@wildo-ai/saas-models 1.0.1

package/dist/esm/resources/utils/repository-dto-builder.utils.js

@@ -0,0 +1,157 @@
+/**
+ * Repository DTO Builder Utilities
+ *
+ * Utilities for deriving repository-level DTOs from schemas.
+ * Repository DTOs exclude virtual fields and populated placeholders,
+ * while including fields needed for virtual field computation.
+ *
+ * Repository DTO Derivation Process:
+ *
+ * 1. Identify Virtual Fields:
+ *    - Virtual fields are computed at runtime, not stored in DB
+ *    - They are excluded from the repository DTO
+ *
+ * 2. Identify Virtual Dependencies:
+ *    - Virtual fields may depend on other stored fields for computation
+ *    - These dependencies must be included in the repository projection
+ *    - Dependencies are declared via isVirtual({ dependencies: ['field1', 'field2'] })
+ *
+ * 3. Exclude Populated Placeholders:
+ *    - Fields that exist only for population (not in mainSchema) are excluded
+ *    - These are added after repository fetch during population phase
+ *
+ * 4. Final Repository DTO:
+ *    - Contains: storable fields + virtual dependencies
+ *    - Excludes: virtual fields + population placeholders
+ *    - Used for MongoDB projection to minimize data transfer
+ *
+ * Example flow:
+ *   mainSchema: { _id, title, assignedToUserId, displayName (virtual) }
+ *   summarySchema: { _id, title, displayName, assignedTo (placeholder) }
+ *   repositoryDto: { _id, title } + dependencies of displayName
+ */
+import { z } from 'zod';
+import { getZodObjectShape, isVirtualField, getVirtualFieldDependencies } from '@wildo-ai/zod-decorators';
+/**
+ * Utility class for deriving repository-level DTOs.
+ *
+ * Repository DTOs are used for MongoDB projections and represent
+ * the actual fields to fetch from the database, excluding:
+ * - Virtual fields (computed at runtime)
+ * - Populated placeholders (fields not in mainSchema, added for population)
+ *
+ * And including:
+ * - Virtual field dependencies (fields needed for virtual computation)
+ */
+export class RepositoryDtoBuilderUtils {
+    /**
+     * Derive repositoryDto from a target schema.
+     *
+     * @param targetSchema - The schema to derive from (e.g., summary schema)
+     * @param mainSchema - The main resource schema (used to identify real vs placeholder fields)
+     * @returns A Zod schema containing only storable/fetchable fields
+     *
+     * @example
+     * ```typescript
+     * const summarySchema = ResourcesSummaryUtils.deriveSummarySchema(MainSchema);
+     * const repoDto = RepositoryDtoBuilderUtils.deriveRepositoryDto(summarySchema, MainSchema);
+     * // repoDto excludes virtuals but includes their dependencies
+     * ```
+     */
+    static deriveRepositoryDto(targetSchema, mainSchema) {
+        const targetShape = getZodObjectShape(targetSchema);
+        const mainShape = getZodObjectShape(mainSchema);
+        if (!targetShape || !mainShape) {
+            // Return empty schema if either is not an object
+            return z.object({});
+        }
+        const repoShape = {};
+        const virtualDeps = new Set();
+        // First pass: identify all virtual field dependencies
+        for (const [fieldName, fieldSchema] of Object.entries(targetShape)) {
+            if (isVirtualField(fieldSchema)) {
+                const deps = getVirtualFieldDependencies(fieldSchema);
+                for (const dep of deps) {
+                    virtualDeps.add(dep);
+                }
+            }
+        }
+        // Second pass: include non-virtual fields that exist in mainSchema
+        for (const [fieldName, fieldSchema] of Object.entries(targetShape)) {
+            // Skip virtual fields - they're computed, not stored
+            if (isVirtualField(fieldSchema)) {
+                continue;
+            }
+            // Skip populated placeholders (fields that don't exist in main schema)
+            if (!mainShape[fieldName]) {
+                continue;
+            }
+            // Include this field
+            repoShape[fieldName] = fieldSchema;
+        }
+        // Third pass: add virtual field dependencies from mainSchema
+        // (Only if they're not already included and exist in mainSchema)
+        for (const dep of virtualDeps) {
+            if (mainShape[dep] && !repoShape[dep]) {
+                repoShape[dep] = mainShape[dep];
+            }
+        }
+        return z.object(repoShape);
+    }
+    /**
+     * Get all fields needed for virtual field computation.
+     *
+     * @param targetSchema - The schema containing virtual fields
+     * @param mainSchema - The main resource schema
+     * @returns Array of field names needed for virtual computation
+     */
+    static getVirtualDependencyFields(targetSchema, mainSchema) {
+        const targetShape = getZodObjectShape(targetSchema);
+        const mainShape = getZodObjectShape(mainSchema);
+        if (!targetShape || !mainShape) {
+            return [];
+        }
+        const deps = new Set();
+        for (const [_fieldName, fieldSchema] of Object.entries(targetShape)) {
+            if (isVirtualField(fieldSchema)) {
+                const fieldDeps = getVirtualFieldDependencies(fieldSchema);
+                for (const dep of fieldDeps) {
+                    // Only include if it exists in mainSchema
+                    if (mainShape[dep]) {
+                        deps.add(dep);
+                    }
+                }
+            }
+        }
+        return Array.from(deps);
+    }
+    /**
+     * Check if a target schema has any virtual fields that require
+     * fields not already in the target schema.
+     *
+     * @param targetSchema - The schema to check
+     * @param mainSchema - The main resource schema
+     * @returns True if additional fields are needed for virtual computation
+     */
+    static hasExternalVirtualDependencies(targetSchema, mainSchema) {
+        const targetShape = getZodObjectShape(targetSchema);
+        const mainShape = getZodObjectShape(mainSchema);
+        if (!targetShape || !mainShape) {
+            return false;
+        }
+        for (const [_fieldName, fieldSchema] of Object.entries(targetShape)) {
+            if (isVirtualField(fieldSchema)) {
+                const deps = getVirtualFieldDependencies(fieldSchema);
+                for (const dep of deps) {
+                    // If a dependency exists in mainSchema but not in targetShape,
+                    // we have external dependencies
+                    if (mainShape[dep] && !targetShape[dep]) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=repository-dto-builder.utils.js.map

package/dist/esm/resources/utils/repository-dto-builder.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-dto-builder.utils.js","sourceRoot":"","sources":["../../../../src/resources/utils/repository-dto-builder.utils.ts"],"names":[],"mappings":"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"}

package/dist/esm/resources/utils/resource-operation-type-guards.utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Type Guard Utilities for Resource Operations
+ *
+ * These helpers assist TypeScript in narrowing union types more efficiently,
+ * reducing the need to check all 7 variants in the union.
+ *
+ * @see TYPING_OPTIMIZATION_PLAN.md
+ */
+import { ResourceConfiguration_Operation } from '../resources-config.shared.schemas.js';
+import { ResourceOperationVariantType } from '../resources.shared.schemas.js';
+/**
+ * Type guard for API_CALL variant
+ */
+export declare function isApiCallOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): operation is Extract<T, {
+    variantType: ResourceOperationVariantType.API_CALL;
+}>;
+/**
+ * Type guard for API_CALL_WITH_CALLBACK variant
+ */
+export declare function isApiCallWithCallbackOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): operation is Extract<T, {
+    variantType: ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
+}>;
+/**
+ * Type guard for CRON_JOB variant
+ */
+export declare function isCronJobOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): operation is Extract<T, {
+    variantType: ResourceOperationVariantType.CRON_JOB;
+}>;
+/**
+ * Type guard for BATCH_JOB variant
+ */
+export declare function isBatchJobOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): operation is Extract<T, {
+    variantType: ResourceOperationVariantType.BATCH_JOB;
+}>;
+/**
+ * Type guard for INTERNAL_CALL variant
+ */
+export declare function isInternalCallOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): operation is Extract<T, {
+    variantType: ResourceOperationVariantType.INTERNAL_CALL;
+}>;
+/**
+ * Type guard for REPOSITORY_ONLY variant
+ */
+export declare function isRepositoryOnlyOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): operation is Extract<T, {
+    variantType: ResourceOperationVariantType.REPOSITORY_ONLY;
+}>;
+//# sourceMappingURL=resource-operation-type-guards.utils.d.ts.map

package/dist/esm/resources/utils/resource-operation-type-guards.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-operation-type-guards.utils.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-operation-type-guards.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACzF,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,QAAQ,CAAA;CAAE,CAAC,CAEjF;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACrG,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,sBAAsB,CAAA;CAAE,CAAC,CAE/F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACzF,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,QAAQ,CAAA;CAAE,CAAC,CAEjF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC1F,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,SAAS,CAAA;CAAE,CAAC,CAElF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC9F,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,aAAa,CAAA;CAAE,CAAC,CAEtF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAChG,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,eAAe,CAAA;CAAE,CAAC,CAExF"}

package/dist/esm/resources/utils/resource-operation-type-guards.utils.js

@@ -0,0 +1,46 @@
+/**
+ * Type Guard Utilities for Resource Operations
+ *
+ * These helpers assist TypeScript in narrowing union types more efficiently,
+ * reducing the need to check all 7 variants in the union.
+ *
+ * @see TYPING_OPTIMIZATION_PLAN.md
+ */
+import { ResourceOperationVariantType } from '../resources.shared.schemas.js';
+/**
+ * Type guard for API_CALL variant
+ */
+export function isApiCallOperation(operation) {
+    return operation.variantType === ResourceOperationVariantType.API_CALL;
+}
+/**
+ * Type guard for API_CALL_WITH_CALLBACK variant
+ */
+export function isApiCallWithCallbackOperation(operation) {
+    return operation.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
+}
+/**
+ * Type guard for CRON_JOB variant
+ */
+export function isCronJobOperation(operation) {
+    return operation.variantType === ResourceOperationVariantType.CRON_JOB;
+}
+/**
+ * Type guard for BATCH_JOB variant
+ */
+export function isBatchJobOperation(operation) {
+    return operation.variantType === ResourceOperationVariantType.BATCH_JOB;
+}
+/**
+ * Type guard for INTERNAL_CALL variant
+ */
+export function isInternalCallOperation(operation) {
+    return operation.variantType === ResourceOperationVariantType.INTERNAL_CALL;
+}
+/**
+ * Type guard for REPOSITORY_ONLY variant
+ */
+export function isRepositoryOnlyOperation(operation) {
+    return operation.variantType === ResourceOperationVariantType.REPOSITORY_ONLY;
+}
+//# sourceMappingURL=resource-operation-type-guards.utils.js.map

package/dist/esm/resources/utils/resource-operation-type-guards.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-operation-type-guards.utils.js","sourceRoot":"","sources":["../../../../src/resources/utils/resource-operation-type-guards.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,sBAAsB,CAAC;AACvF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,SAAS,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,aAAa,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,eAAe,CAAC;AAChF,CAAC"}

package/dist/esm/resources/utils/resource-polymorphism.factory.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Resource Polymorphism — Factory Configuration (Phase 3)
+ *
+ * Provides `createPolymorphicResourceConfigurations()` which takes a polymorphic
+ * declaration + shared resource configuration, and produces N factory functions
+ * (one per variant) that can be spread into the resource configurations factory map.
+ *
+ * Key transformation: `polymorphicRole` on operation variants is resolved to
+ * standard `roles` for each variant's scope.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md — Phase 3
+ */
+import { z } from 'zod';
+import type { ResourceConfiguration_InitializationFactory, ResourceConfiguration_Operation_BuilderParameters, ResourceConfiguration_OperationVariant_BuilderParameters, ResourceConfiguration_InheritanceSchemaDefinition, ResourceConfiguration_AutoVariants, CollectionViewFields_Search } from '../resources-config.shared.schemas.js';
+import type { CoreResourceOperation } from '../resources.shared.core.definitions.js';
+import type { PersistenceAdapterType } from '../resources-config.shared.schemas.js';
+import type { EnumLikeType } from '@wildo-ai/zod-decorators';
+import type { PolymorphicSchemaDeclaration } from './resource-polymorphism.schemas.js';
+/**
+ * Distributive Omit — preserves union members individually.
+ * Standard `Omit<A | B, K>` collapses to common keys only, losing per-member properties.
+ * This helper distributes the Omit over each union member, preserving all variant-specific fields.
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends any ? Omit<T, K> : never;
+/**
+ * Operation variant with `polymorphicRole` support.
+ * Extends the standard variant by adding `polymorphicRole` as an alternative to `roles`.
+ *
+ * - `polymorphicRole`: `Record<ResourceType, string[]>` — role mapping per parent resource type.
+ *   The factory resolves this to standard `roles` for each generated variant.
+ * - `roles`: standard roles array — used directly (e.g., for admin variants).
+ *
+ * If both `polymorphicRole` and `roles` are provided, `polymorphicRole` takes precedence
+ * for the matching parent resource type. If the parent isn't in `polymorphicRole`, `roles` is used as fallback.
+ */
+/**
+ * Polymorphic variant type. Intersects with CollectionViewFields_Search so that
+ * SEARCH operation variants (including REPOSITORY_ONLY) can specify isSearchable,
+ * searchableFields, filterFields, sortFields, etc. All fields are optional.
+ */
+export type PolymorphicOperationVariant<TMainSchema extends z.ZodTypeAny = z.ZodTypeAny> = DistributiveOmit<ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>, 'roles'> & CollectionViewFields_Search & {
+    /**
+     * Role mapping per parent resource type.
+     * The factory resolves this into standard `roles` for each generated variant.
+     *
+     * @example
+     * polymorphicRole: {
+     *   'organizations': ['ORG_OWNER', 'ORG_ADMIN'],
+     *   'users': [],  // user themselves — no role check
+     *        * }
+     */
+    polymorphicRole?: Record<string, string[]>;
+    /** Standard roles — used directly or as fallback when polymorphicRole doesn't have the parent */
+    roles?: string[];
+};
+/**
+ * Operation configuration with polymorphic role support.
+ */
+export type PolymorphicOperationConfig<TMainSchema extends z.ZodTypeAny = z.ZodAny> = Omit<ResourceConfiguration_Operation_BuilderParameters<TMainSchema>, 'variants'> & {
+    variants: PolymorphicOperationVariant<TMainSchema>[];
+};
+/**
+ * Shared resource configuration for polymorphic resources.
+ * Contains everything that's common across all variants.
+ *
+ * Notable omissions (derived from the polymorphic declaration):
+ * - `mainSchema` — derived per variant from the declaration
+ * - `resourceIdentifier` — derived per variant
+ * - `resourceFieldIdentifier` — derived per variant
+ * - `resourceRelationships` — provided at factory call time by the registry
+ */
+export interface PolymorphicResourceConfig<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> {
+    /** Whether this resource is disabled (default: false) */
+    isDisabled?: boolean;
+    /** Whether this is a system resource (default: false) */
+    isSystemResource?: boolean;
+    /** Persistence adapter type (default: 'mongodb') */
+    persistenceAdapter?: PersistenceAdapterType;
+    /** Core operations enabled for this resource */
+    coreOperations: TCoreOperationEnum[];
+    /** Custom operations enum (if any) */
+    customOperation?: TCustomOperationEnum;
+    /** Operations configuration — supports polymorphicRole on variants */
+    operationsConfiguration: Record<string, PolymorphicOperationConfig<TMainSchema>>;
+    /** Auto-generated operation variants configuration */
+    autoVariants?: ResourceConfiguration_AutoVariants;
+    /** Inheritance schema definition (usually from SchemaFamily) */
+    inheritenceSchemaDefinition?: ResourceConfiguration_InheritanceSchemaDefinition<any, TMainSchema>;
+}
+/**
+ * Create N resource configuration factories from a polymorphic declaration.
+ *
+ * For each variant in the declaration, produces a standard
+ * `ResourceConfiguration_InitializationFactory` that can be registered in the factory map.
+ *
+ * The key transformation: `polymorphicRole` on operation variants is resolved to
+ * standard `roles` for each variant's parent resource type.
+ *
+ * @returns Record mapping variant resource type → factory function
+ *
+ * @example
+ * ```typescript
+ * const billingAccountFactories = createPolymorphicResourceConfigurations(
+ *   billingAccountsPolymorphicDeclaration,
+ *   {
+ *     coreOperations: [CoreResourceOperation.READ, CoreResourceOperation.LIST, ...],
+ *     operationsConfiguration: {
+ *       [CoreResourceOperation.READ]: {
+ *         variants: [{
+ *           variantType: ResourceOperationVariantType.API_CALL,
+ *           isDefault: true,
+ *           polymorphicRole: {
+ *             'organizations': [CORE_ORG_ROLES.ORG_OWNER],
+ *             'users': [],
+ *           },
+ *           riskLevel: ResourceOperationRiskLevel.LOW,
+ *         }],
+ *       },
+ *     },
+ *   },
+ * );
+ * // → {
+ * //     'organizationBillingAccounts': (rels) => ResourceConfiguration,
+ * //     'userBillingAccounts': (rels) => ResourceConfiguration,
+ * //   }
+ * ```
+ */
+export declare function createPolymorphicResourceConfigurations<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny>(declaration: PolymorphicSchemaDeclaration<TMainSchema>, sharedConfig: PolymorphicResourceConfig<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>): Record<string, ResourceConfiguration_InitializationFactory<TCustomOperationEnum, TCoreOperationEnum, any>>;
+export {};
+//# sourceMappingURL=resource-polymorphism.factory.d.ts.map

package/dist/esm/resources/utils/resource-polymorphism.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-polymorphism.factory.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.factory.ts"],"names":[],"mappings":"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"}

package/dist/esm/resources/utils/resource-polymorphism.factory.js

@@ -0,0 +1,133 @@
+/**
+ * Resource Polymorphism — Factory Configuration (Phase 3)
+ *
+ * Provides `createPolymorphicResourceConfigurations()` which takes a polymorphic
+ * declaration + shared resource configuration, and produces N factory functions
+ * (one per variant) that can be spread into the resource configurations factory map.
+ *
+ * Key transformation: `polymorphicRole` on operation variants is resolved to
+ * standard `roles` for each variant's scope.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md — Phase 3
+ */
+import { createResourceConfiguration_Initialization } from '../resources-config.shared.factory.js';
+// =============================================================================
+// MAIN FUNCTION
+// =============================================================================
+/**
+ * Create N resource configuration factories from a polymorphic declaration.
+ *
+ * For each variant in the declaration, produces a standard
+ * `ResourceConfiguration_InitializationFactory` that can be registered in the factory map.
+ *
+ * The key transformation: `polymorphicRole` on operation variants is resolved to
+ * standard `roles` for each variant's parent resource type.
+ *
+ * @returns Record mapping variant resource type → factory function
+ *
+ * @example
+ * ```typescript
+ * const billingAccountFactories = createPolymorphicResourceConfigurations(
+ *   billingAccountsPolymorphicDeclaration,
+ *   {
+ *     coreOperations: [CoreResourceOperation.READ, CoreResourceOperation.LIST, ...],
+ *     operationsConfiguration: {
+ *       [CoreResourceOperation.READ]: {
+ *         variants: [{
+ *           variantType: ResourceOperationVariantType.API_CALL,
+ *           isDefault: true,
+ *           polymorphicRole: {
+ *             'organizations': [CORE_ORG_ROLES.ORG_OWNER],
+ *             'users': [],
+ *           },
+ *           riskLevel: ResourceOperationRiskLevel.LOW,
+ *         }],
+ *       },
+ *     },
+ *   },
+ * );
+ * // → {
+ * //     'organizationBillingAccounts': (rels) => ResourceConfiguration,
+ * //     'userBillingAccounts': (rels) => ResourceConfiguration,
+ * //   }
+ * ```
+ */
+export function createPolymorphicResourceConfigurations(declaration, sharedConfig) {
+    const result = {};
+    for (const [, variant] of declaration.variants) {
+        const resolvedOpsConfig = resolveOperationsForVariant(sharedConfig.operationsConfiguration, variant);
+        // Determine the schema for this variant:
+        // - If SchemaFamily, use the rebuilt union
+        // - If plain ZodObject, use the variant schema directly
+        const variantMainSchema = variant.schema;
+        // Determine inheritenceSchemaDefinition:
+        // - If SchemaFamily, use the rebuilt family's inheritenceSchemaDefinition
+        // - Otherwise, use the shared config's (if any)
+        const inheritenceSchemaDefinition = variant.schemaFamily
+            ? variant.schemaFamily.inheritenceSchemaDefinition
+            : sharedConfig.inheritenceSchemaDefinition;
+        // Lazy factory: relationships are provided at registry call time, not at declaration time
+        result[variant.resourceType] = (resourcesRelationships) => createResourceConfiguration_Initialization({
+            isDisabled: sharedConfig.isDisabled,
+            mainSchema: variantMainSchema,
+            resourceIdentifier: variant.resourceType,
+            resourceFieldIdentifier: variant.fieldIdentifier,
+            resourceRelationships: resourcesRelationships,
+            inheritenceSchemaDefinition,
+            persistenceAdapter: sharedConfig.persistenceAdapter,
+            isSystemResource: sharedConfig.isSystemResource,
+            coreOperations: sharedConfig.coreOperations,
+            customOperation: sharedConfig.customOperation,
+            operationsConfiguration: resolvedOpsConfig,
+            autoVariants: sharedConfig.autoVariants,
+        });
+    }
+    return result;
+}
+// =============================================================================
+// INTERNALS
+// =============================================================================
+/**
+ * Resolve `polymorphicRole` → `roles` for each operation variant for a specific scope variant.
+ */
+function resolveOperationsForVariant(operationsConfiguration, variant) {
+    const resolved = {};
+    for (const [operationKey, opConfig] of Object.entries(operationsConfiguration)) {
+        const resolvedVariants = [];
+        for (const opVariant of opConfig.variants) {
+            const { polymorphicRole, roles: fallbackRoles, ...rest } = opVariant;
+            let resolvedRoles;
+            if (polymorphicRole) {
+                // Resolve from polymorphicRole map using the parent resource type
+                const parentType = variant.parentResourceType;
+                if (parentType in polymorphicRole) {
+                    resolvedRoles = polymorphicRole[parentType];
+                }
+                else if (fallbackRoles) {
+                    resolvedRoles = fallbackRoles;
+                }
+                else {
+                    throw new Error(`[PolymorphicFactory] Operation "${operationKey}" variant has polymorphicRole but no entry ` +
+                        `for parentResourceType="${parentType}" and no fallback roles. ` +
+                        `Either add "${parentType}" to polymorphicRole or provide fallback roles.`);
+                }
+            }
+            else if (fallbackRoles) {
+                resolvedRoles = fallbackRoles;
+            }
+            else {
+                throw new Error(`[PolymorphicFactory] Operation "${operationKey}" variant has neither polymorphicRole nor roles.`);
+            }
+            resolvedVariants.push({
+                ...rest,
+                roles: resolvedRoles,
+            });
+        }
+        resolved[operationKey] = {
+            ...opConfig,
+            variants: resolvedVariants,
+        };
+    }
+    return resolved;
+}
+//# sourceMappingURL=resource-polymorphism.factory.js.map

package/dist/esm/resources/utils/resource-polymorphism.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-polymorphism.factory.js","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,0CAA0C,EAAE,MAAM,oCAAoC,CAAC;AAsGhG,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,uCAAuC,CAKrD,WAAsD,EACtD,YAA8F;IAE9F,MAAM,MAAM,GAA+G,EAAE,CAAC;IAE9H,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC/C,MAAM,iBAAiB,GAAG,2BAA2B,CACnD,YAAY,CAAC,uBAAuB,EACpC,OAAO,CACR,CAAC;QAEF,yCAAyC;QACzC,2CAA2C;QAC3C,wDAAwD;QACxD,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;QAEzC,yCAAyC;QACzC,0EAA0E;QAC1E,gDAAgD;QAChD,MAAM,2BAA2B,GAAG,OAAO,CAAC,YAAY;YACtD,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,2BAAkC;YACzD,CAAC,CAAC,YAAY,CAAC,2BAA2B,CAAC;QAE7C,0FAA0F;QAC1F,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,sBAAsB,EAAE,EAAE,CACxD,0CAA0C,CAAC;YACzC,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,UAAU,EAAE,iBAAiB;YAC7B,kBAAkB,EAAE,OAAO,CAAC,YAA4B;YACxD,uBAAuB,EAAE,OAAO,CAAC,eAAe;YAChD,qBAAqB,EAAE,sBAAsB;YAC7C,2BAA2B;YAC3B,kBAAkB,EAAE,YAAY,CAAC,kBAAkB;YACnD,gBAAgB,EAAE,YAAY,CAAC,gBAAgB;YAC/C,cAAc,EAAE,YAAY,CAAC,cAAqB;YAClD,eAAe,EAAE,YAAY,CAAC,eAAsB;YACpD,uBAAuB,EAAE,iBAAwB;YACjD,YAAY,EAAE,YAAY,CAAC,YAAY;SACxC,CAAC,CAAC;IACP,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;GAEG;AACH,SAAS,2BAA2B,CAClC,uBAAgF,EAChF,OAAgD;IAEhD,MAAM,QAAQ,GAAmF,EAAE,CAAC;IAEpG,KAAK,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAC/E,MAAM,gBAAgB,GAA4E,EAAE,CAAC;QAErG,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAC1C,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,CAAC;YAErE,IAAI,aAAuB,CAAC;YAE5B,IAAI,eAAe,EAAE,CAAC;gBACpB,kEAAkE;gBAClE,MAAM,UAAU,GAAG,OAAO,CAAC,kBAA4B,CAAC;gBACxD,IAAI,UAAU,IAAI,eAAe,EAAE,CAAC;oBAClC,aAAa,GAAG,eAAe,CAAC,UAAU,CAAE,CAAC;gBAC/C,CAAC;qBAAM,IAAI,aAAa,EAAE,CAAC;oBACzB,aAAa,GAAG,aAAa,CAAC;gBAChC,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,KAAK,CACb,mCAAmC,YAAY,6CAA6C;wBAC5F,2BAA2B,UAAU,2BAA2B;wBAChE,eAAe,UAAU,iDAAiD,CAC3E,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,IAAI,aAAa,EAAE,CAAC;gBACzB,aAAa,GAAG,aAAa,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CACb,mCAAmC,YAAY,kDAAkD,CAClG,CAAC;YACJ,CAAC;YAED,gBAAgB,CAAC,IAAI,CAAC;gBACpB,GAAG,IAAI;gBACP,KAAK,EAAE,aAAa;aACoD,CAAC,CAAC;QAC9E,CAAC;QAED,QAAQ,CAAC,YAAY,CAAC,GAAG;YACvB,GAAG,QAAQ;YACX,QAAQ,EAAE,gBAAgB;SAC3B,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}