@wildo-ai/saas-models 1.0.1

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

@@ -0,0 +1,122 @@
+/**
+ * Resource Polymorphism — Relationship Declaration (Phase 2)
+ *
+ * Provides helpers to generate N relationships from a polymorphic declaration:
+ *
+ * 1. `createPolymorphicScopeRelationships(declaration)` — generates scope relationships
+ *    (e.g., ORGANIZATIONS → organizationBillingAccounts) for each `isPrimaryScope: true` variant.
+ *
+ * 2. `createPolymorphicRelationships(parentDecl, childDeclOrType, ...)` — generates parent-child
+ *    relationships for each variant (e.g., organizationBillingAccounts → organizationSubscriptions).
+ *
+ * Both use existing `createResourcesRelationship()` internally — the output is standard
+ * `ResourceRelationship[]` spread into the registry.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md — Phase 2
+ */
+import type { ResourceRelationship } from '../resources.shared.schemas.js';
+import { RelationshipNature, ResourceRelationshipCardinality, type ResourceRelationshipConditionFn } from '../resources.shared.schemas.js';
+import type { RelationshipContextPolicy } from '../context-policy.shared.schemas.js';
+import type { ChildOperationsConfig, ResourceRelationshipDiscriminator } from '../child-operations.shared.schemas.js';
+import type { RelationshipDisplayConfig } from '../relationship-display.shared.schemas.js';
+import type { ResourceType } from '../resources.shared.core.definitions.js';
+import type { PolymorphicSchemaDeclaration } from './resource-polymorphism.schemas.js';
+/**
+ * Options propagated to each generated relationship.
+ *
+ * When `discriminator` or `condition` is provided, every generated variant
+ * relationship will carry the same condition. This is useful when the
+ * polymorphic expansion should be universally conditional (e.g., all billing
+ * account variants → subscriptions only when account is active).
+ *
+ * For variant-specific conditions, apply discriminator/condition directly
+ * on individual `createResourcesRelationship()` calls instead.
+ */
+export interface PolymorphicRelationshipOptions {
+    /** Context policy for this relationship */
+    contextPolicy?: RelationshipContextPolicy;
+    /** High-level semantic meaning for each generated relationship */
+    nature: RelationshipNature;
+    /** Child operations configuration (lifecycle + nested DTOs) */
+    childOperations?: ChildOperationsConfig;
+    /** Frontend display configuration */
+    display?: RelationshipDisplayConfig;
+    /** Static discriminator filter — forwarded to each generated variant relationship */
+    discriminator?: ResourceRelationshipDiscriminator;
+    /** Function-based condition — forwarded to each generated variant relationship */
+    condition?: ResourceRelationshipConditionFn;
+    /** Foreign key field override (usually not needed — derived automatically) */
+    foreignKeyField?: string;
+}
+/**
+ * Generate scope relationships for a polymorphic declaration.
+ *
+ * For each variant with `isPrimaryScope: true`, generates:
+ *   parentResourceType → variantResourceType (ONE:MANY, isPrimaryScope: true)
+ *
+ * For `isPrimaryScope: false` variants, this function generates nothing —
+ * non-primary-scope variants get their parent relationship from
+ * `createPolymorphicRelationships()` instead.
+ *
+ * @example
+ * ```typescript
+ * // In the registry:
+ * ...createPolymorphicScopeRelationships(billingAccountsPolymorphicDeclaration),
+ * // Generates:
+ * //   ORGANIZATIONS → organizationBillingAccounts (isPrimaryScope: true)
+ * //   USERS → userBillingAccounts (isPrimaryScope: true)
+ * ```
+ */
+export declare function createPolymorphicScopeRelationships(declaration: PolymorphicSchemaDeclaration, options: {
+    /** Child operations for the scope relationship (e.g., cascade delete) */
+    childOperations?: ChildOperationsConfig;
+    /** Context policy for the scope relationship */
+    contextPolicy?: RelationshipContextPolicy;
+    /** High-level semantic meaning for each generated relationship */
+    nature: RelationshipNature;
+    /** Display config for the scope relationship */
+    display?: RelationshipDisplayConfig;
+    /** Cardinality from parent → child. Defaults to MANY. Use ONE for singleton resources. */
+    childCardinality?: ResourceRelationshipCardinality;
+}): ResourceRelationship[];
+/**
+ * Generate parent-child relationships between a polymorphic parent and a child.
+ *
+ * The child can be:
+ * - **Another polymorphic declaration**: generates variant-to-variant relationships
+ *   (e.g., organizationBillingAccounts → organizationSubscriptions)
+ * - **A simple resource type string**: generates variant-to-same-child relationships
+ *   (e.g., organizationBillingAccounts → prices, if prices are NOT polymorphic)
+ *
+ * When both parent and child are polymorphic, the function matches variants by
+ * `parentResourceType` — each parent variant maps to the child variant with the
+ * same parent resource type.
+ *
+ * @example
+ * ```typescript
+ * // Polymorphic parent → polymorphic child:
+ * ...createPolymorphicRelationships(
+ *   billingAccountsPolymorphicDeclaration,
+ *   subscriptionsPolymorphicDeclaration,
+ *   ResourceRelationshipCardinality.ONE,
+ *   ResourceRelationshipCardinality.MANY,
+ *   { childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: 'IMMEDIATE', maxDepth: 1 } } } },
+ * ),
+ * // Generates:
+ * //   organizationBillingAccounts → organizationSubscriptions
+ * //   userBillingAccounts → userSubscriptions
+ *
+ * // Polymorphic parent → non-polymorphic child:
+ * ...createPolymorphicRelationships(
+ *   billingAccountsPolymorphicDeclaration,
+ *   CoreResourceType.PRICES,
+ *   ResourceRelationshipCardinality.ONE,
+ *   ResourceRelationshipCardinality.MANY,
+ * ),
+ * // Generates:
+ * //   organizationBillingAccounts → prices
+ * //   userBillingAccounts → prices
+ * ```
+ */
+export declare function createPolymorphicRelationships(parentDeclaration: PolymorphicSchemaDeclaration, childDeclarationOrType: PolymorphicSchemaDeclaration | ResourceType, parentCardinality: ResourceRelationshipCardinality, childCardinality: ResourceRelationshipCardinality, options: PolymorphicRelationshipOptions): ResourceRelationship[];
+//# sourceMappingURL=resource-polymorphism.relationships.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource-polymorphism.relationships.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EACL,kBAAkB,EAClB,+BAA+B,EAC/B,KAAK,+BAA+B,EACrC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,KAAK,EAAE,qBAAqB,EAAE,iCAAiC,EAAE,MAAM,oCAAoC,CAAC;AACnH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,iCAAiC,CAAC;AAMpF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,8BAA8B;IAC7C,2CAA2C;IAC3C,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,qCAAqC;IACrC,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,qFAAqF;IACrF,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAClD,kFAAkF;IAClF,SAAS,CAAC,EAAE,+BAA+B,CAAC;IAC5C,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,4BAA4B,EACzC,OAAO,EAAE;IACP,yEAAyE;IACzE,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,gDAAgD;IAChD,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gDAAgD;IAChD,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,+BAA+B,CAAC;CACpD,GACA,oBAAoB,EAAE,CAyBxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,4BAA4B,EAC/C,sBAAsB,EAAE,4BAA4B,GAAG,YAAY,EACnE,iBAAiB,EAAE,+BAA+B,EAClD,gBAAgB,EAAE,+BAA+B,EACjD,OAAO,EAAE,8BAA8B,GACtC,oBAAoB,EAAE,CA8CxB"}

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

@@ -0,0 +1,131 @@
+/**
+ * Resource Polymorphism — Relationship Declaration (Phase 2)
+ *
+ * Provides helpers to generate N relationships from a polymorphic declaration:
+ *
+ * 1. `createPolymorphicScopeRelationships(declaration)` — generates scope relationships
+ *    (e.g., ORGANIZATIONS → organizationBillingAccounts) for each `isPrimaryScope: true` variant.
+ *
+ * 2. `createPolymorphicRelationships(parentDecl, childDeclOrType, ...)` — generates parent-child
+ *    relationships for each variant (e.g., organizationBillingAccounts → organizationSubscriptions).
+ *
+ * Both use existing `createResourcesRelationship()` internally — the output is standard
+ * `ResourceRelationship[]` spread into the registry.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md — Phase 2
+ */
+import { createResourcesRelationship } from '../resources-relationships.shared.factory.js';
+import { ResourceRelationshipCardinality, } from '../resources.shared.schemas.js';
+// =============================================================================
+// SCOPE RELATIONSHIPS
+// =============================================================================
+/**
+ * Generate scope relationships for a polymorphic declaration.
+ *
+ * For each variant with `isPrimaryScope: true`, generates:
+ *   parentResourceType → variantResourceType (ONE:MANY, isPrimaryScope: true)
+ *
+ * For `isPrimaryScope: false` variants, this function generates nothing —
+ * non-primary-scope variants get their parent relationship from
+ * `createPolymorphicRelationships()` instead.
+ *
+ * @example
+ * ```typescript
+ * // In the registry:
+ * ...createPolymorphicScopeRelationships(billingAccountsPolymorphicDeclaration),
+ * // Generates:
+ * //   ORGANIZATIONS → organizationBillingAccounts (isPrimaryScope: true)
+ * //   USERS → userBillingAccounts (isPrimaryScope: true)
+ * ```
+ */
+export function createPolymorphicScopeRelationships(declaration, options) {
+    const relationships = [];
+    const childCardinality = options?.childCardinality ?? ResourceRelationshipCardinality.MANY;
+    for (const [, variant] of declaration.variants) {
+        if (!variant.isPrimaryScope)
+            continue;
+        relationships.push(createResourcesRelationship(variant.parentResourceType, variant.resourceType, ResourceRelationshipCardinality.ONE, childCardinality, {
+            isPrimaryScope: true,
+            nature: options.nature,
+            ...(options?.childOperations ? { childOperations: options.childOperations } : {}),
+            ...(options?.contextPolicy ? { contextPolicy: options.contextPolicy } : {}),
+            ...(options?.display ? { display: options.display } : {}),
+        }));
+    }
+    return relationships;
+}
+// =============================================================================
+// PARENT-CHILD RELATIONSHIPS
+// =============================================================================
+/**
+ * Generate parent-child relationships between a polymorphic parent and a child.
+ *
+ * The child can be:
+ * - **Another polymorphic declaration**: generates variant-to-variant relationships
+ *   (e.g., organizationBillingAccounts → organizationSubscriptions)
+ * - **A simple resource type string**: generates variant-to-same-child relationships
+ *   (e.g., organizationBillingAccounts → prices, if prices are NOT polymorphic)
+ *
+ * When both parent and child are polymorphic, the function matches variants by
+ * `parentResourceType` — each parent variant maps to the child variant with the
+ * same parent resource type.
+ *
+ * @example
+ * ```typescript
+ * // Polymorphic parent → polymorphic child:
+ * ...createPolymorphicRelationships(
+ *   billingAccountsPolymorphicDeclaration,
+ *   subscriptionsPolymorphicDeclaration,
+ *   ResourceRelationshipCardinality.ONE,
+ *   ResourceRelationshipCardinality.MANY,
+ *   { childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: 'IMMEDIATE', maxDepth: 1 } } } },
+ * ),
+ * // Generates:
+ * //   organizationBillingAccounts → organizationSubscriptions
+ * //   userBillingAccounts → userSubscriptions
+ *
+ * // Polymorphic parent → non-polymorphic child:
+ * ...createPolymorphicRelationships(
+ *   billingAccountsPolymorphicDeclaration,
+ *   CoreResourceType.PRICES,
+ *   ResourceRelationshipCardinality.ONE,
+ *   ResourceRelationshipCardinality.MANY,
+ * ),
+ * // Generates:
+ * //   organizationBillingAccounts → prices
+ * //   userBillingAccounts → prices
+ * ```
+ */
+export function createPolymorphicRelationships(parentDeclaration, childDeclarationOrType, parentCardinality, childCardinality, options) {
+    const relationships = [];
+    const isChildPolymorphic = typeof childDeclarationOrType !== 'string' && '__polymorphic' in childDeclarationOrType;
+    for (const [parentResourceType, parentVariant] of parentDeclaration.variants) {
+        let childResourceType;
+        if (isChildPolymorphic) {
+            const childDeclaration = childDeclarationOrType;
+            const childVariant = childDeclaration.variants.get(parentResourceType);
+            if (!childVariant) {
+                throw new Error(`[PolymorphicRelationships] Parent variant "${parentVariant.resourceType}" ` +
+                    `(parentResourceType="${parentResourceType}") has no matching child variant ` +
+                    `in child declaration "${childDeclaration.baseResourceType}". ` +
+                    `Both polymorphic declarations must have the same set of parentResourceType values.`);
+            }
+            childResourceType = childVariant.resourceType;
+        }
+        else {
+            // Child is a simple (non-polymorphic) resource type
+            childResourceType = childDeclarationOrType;
+        }
+        relationships.push(createResourcesRelationship(parentVariant.resourceType, childResourceType, parentCardinality, childCardinality, {
+            nature: options.nature,
+            ...(options?.contextPolicy ? { contextPolicy: options.contextPolicy } : {}),
+            ...(options?.childOperations ? { childOperations: options.childOperations } : {}),
+            ...(options?.display ? { display: options.display } : {}),
+            ...(options?.discriminator ? { discriminator: options.discriminator } : {}),
+            ...(options?.condition ? { condition: options.condition } : {}),
+            ...(options?.foreignKeyField ? { foreignKeyField: options.foreignKeyField } : {}),
+        }));
+    }
+    return relationships;
+}
+//# sourceMappingURL=resource-polymorphism.relationships.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource-polymorphism.relationships.js","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,2CAA2C,CAAC;AAExF,OAAO,EAEL,+BAA+B,GAEhC,MAAM,6BAA6B,CAAC;AAuCrC,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mCAAmC,CACjD,WAAyC,EACzC,OAWC;IAED,MAAM,aAAa,GAA2B,EAAE,CAAC;IACjD,MAAM,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,+BAA+B,CAAC,IAAI,CAAC;IAE3F,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC/C,IAAI,CAAC,OAAO,CAAC,cAAc;YAAE,SAAS;QAEtC,aAAa,CAAC,IAAI,CAChB,2BAA2B,CACzB,OAAO,CAAC,kBAAkB,EAC1B,OAAO,CAAC,YAAY,EACpB,+BAA+B,CAAC,GAAG,EACnC,gBAAgB,EAChB;YACE,cAAc,EAAE,IAAI;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1D,CACF,CACF,CAAC;IACJ,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,8BAA8B,CAC5C,iBAA+C,EAC/C,sBAAmE,EACnE,iBAAkD,EAClD,gBAAiD,EACjD,OAAuC;IAEvC,MAAM,aAAa,GAA2B,EAAE,CAAC;IACjD,MAAM,kBAAkB,GAAG,OAAO,sBAAsB,KAAK,QAAQ,IAAI,eAAe,IAAI,sBAAsB,CAAC;IAEnH,KAAK,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,IAAI,iBAAiB,CAAC,QAAQ,EAAE,CAAC;QAC7E,IAAI,iBAAyB,CAAC;QAE9B,IAAI,kBAAkB,EAAE,CAAC;YACvB,MAAM,gBAAgB,GAAG,sBAAsD,CAAC;YAChF,MAAM,YAAY,GAAG,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;YAEvE,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CACb,8CAA8C,aAAa,CAAC,YAAY,IAAI;oBAC5E,wBAAwB,kBAA4B,mCAAmC;oBACvF,yBAAyB,gBAAgB,CAAC,gBAAgB,KAAK;oBAC/D,oFAAoF,CACrF,CAAC;YACJ,CAAC;YAED,iBAAiB,GAAG,YAAY,CAAC,YAAY,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,oDAAoD;YACpD,iBAAiB,GAAG,sBAAgC,CAAC;QACvD,CAAC;QAED,aAAa,CAAC,IAAI,CAChB,2BAA2B,CACzB,aAAa,CAAC,YAAY,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB;YACE,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClF,CACF,CACF,CAAC;IACJ,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}

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

@@ -0,0 +1,128 @@
+/**
+ * Resource Polymorphism — Schema Declaration (Phase 1)
+ *
+ * Provides `declarePolymorphicSchemas()` which takes a base schema and a list
+ * of parent variant definitions, and produces a `PolymorphicSchemaDeclaration`
+ * containing pre-computed schemas for each variant (base + injected parent FK).
+ *
+ * Supports both plain `z.ZodObject` and `SchemaFamily` as base schema input.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md — Phase 1
+ */
+import { z } from 'zod';
+import { type PolymorphicParentVariantDefinition } from './resource-polymorphism.utils.js';
+import type { SchemaFamily, VariantConfig } from './schema-family-builder.utils.js';
+import type { ResourceType } from '../resources.shared.core.definitions.js';
+/**
+ * Full variant definition including isPrimaryScope flag.
+ * Used as input to `declarePolymorphicSchemas()`.
+ */
+export interface PolymorphicVariantDefinition extends PolymorphicParentVariantDefinition {
+    /**
+     * Whether this variant's parent is a primary scope entity.
+     * - `true`: identity field injected (e.g., `organizationId`), authorization scope-aware
+     * - `false`: parent FK injected (e.g., `projectId`), scope inherited from parent chain
+     */
+    isPrimaryScope: boolean;
+}
+/**
+ * A single resolved variant within a polymorphic declaration.
+ * Contains all derived naming + the transformed schema.
+ */
+export interface PolymorphicResolvedVariant<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** The parent resource type this variant is parented to */
+    parentResourceType: ResourceType;
+    /** The parent's field identifier (e.g., 'organizationId') */
+    parentFieldIdentifier: string;
+    /** Whether this variant's parent is a primary scope entity */
+    isPrimaryScope: boolean;
+    /** Derived variant resource type (e.g., 'organizationBillingAccounts') */
+    resourceType: string;
+    /** Derived variant field identifier (e.g., 'organizationBillingAccountId') */
+    fieldIdentifier: string;
+    /** Derived collection name (same as resourceType) */
+    collectionName: string;
+    /** Derived kebab-case route segment */
+    routeSegment: string;
+    /** Derived CONSTANT_CASE enum key */
+    enumKey: string;
+    /** Transformed schema: base schema + parent FK field injected */
+    schema: TSchema;
+    /** If baseSchema was a SchemaFamily, this holds the rebuilt family for this variant */
+    schemaFamily?: SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>>;
+}
+/**
+ * The output of `declarePolymorphicSchemas()`.
+ * Contains the base declaration + pre-computed variants map.
+ */
+export interface PolymorphicSchemaDeclaration<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** Marker for runtime type checking */
+    __polymorphic: true;
+    /** Base resource type (e.g., 'billingAccounts') — the abstract logical name */
+    baseResourceType: string;
+    /** Base field identifier (e.g., 'billingAccountId') */
+    baseFieldIdentifier: string;
+    /** Base CONSTANT_CASE enum key (e.g., 'BILLING_ACCOUNTS') */
+    baseEnumKey: string;
+    /** The original base schema (before variant transformation) */
+    baseSchema: TSchema;
+    /** The original variant definitions as provided by the developer */
+    variantDefinitions: PolymorphicVariantDefinition[];
+    /** Pre-computed map: parentResourceType → resolved variant (naming + transformed schema) */
+    variants: Map<ResourceType, PolymorphicResolvedVariant<TSchema>>;
+}
+/**
+ * Input configuration for `declarePolymorphicSchemas()`.
+ */
+export interface DeclarePolymorphicSchemasConfig<TSchema extends z.ZodTypeAny> {
+    /** Base resource type (e.g., 'billingAccounts') */
+    baseResourceType: string;
+    /** Base field identifier (e.g., 'billingAccountId') */
+    baseFieldIdentifier: string;
+    /** Base CONSTANT_CASE enum key (e.g., 'BILLING_ACCOUNTS') */
+    baseEnumKey: string;
+    /**
+     * Base schema — either a plain z.ZodObject or a SchemaFamily result.
+     * Must NOT already contain identity fields (organizationId, userId, etc.) — they are injected per variant.
+     */
+    baseSchema: TSchema;
+    /** Variant definitions — one per parent resource */
+    variants: PolymorphicVariantDefinition[];
+}
+/**
+ * Declare polymorphic schemas for a base resource.
+ *
+ * For each variant definition, this function:
+ * 1. Derives all naming identifiers using `ResourcePolymorphismUtils`
+ * 2. Clones the base schema and injects the parent's field identifier as a new FK field
+ * 3. If the base schema is a `SchemaFamily`, rebuilds the family per variant
+ * 4. Returns a `PolymorphicSchemaDeclaration` with pre-computed variants
+ *
+ * @example
+ * ```typescript
+ * // Plain z.ZodObject base:
+ * const billingDeclaration = declarePolymorphicSchemas({
+ *   baseResourceType: 'billingAccounts',
+ *   baseFieldIdentifier: 'billingAccountId',
+ *   baseEnumKey: 'BILLING_ACCOUNTS',
+ *   baseSchema: BillingAccountBaseSchema,
+ *   variants: [
+ *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },
+ *     { parentResourceType: 'users',         parentFieldIdentifier: 'userId',         isPrimaryScope: true },
+ *   ],
+ * });
+ *
+ * // SchemaFamily base:
+ * const subscriptionDeclaration = declarePolymorphicSchemas({
+ *   baseResourceType: 'subscriptions',
+ *   baseFieldIdentifier: 'subscriptionId',
+ *   baseEnumKey: 'SUBSCRIPTIONS',
+ *   baseSchema: SubscriptionSchemaFamily,  // result of createSchemaFamily()
+ *   variants: [
+ *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },
+ *   ],
+ * });
+ * ```
+ */
+export declare function declarePolymorphicSchemas<TSchema extends z.ZodTypeAny>(config: DeclarePolymorphicSchemasConfig<TSchema>): PolymorphicSchemaDeclaration<TSchema>;
+//# sourceMappingURL=resource-polymorphism.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource-polymorphism.schemas.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA6B,KAAK,kCAAkC,EAAiC,MAAM,+BAA+B,CAAC;AAClJ,OAAO,KAAK,EAAE,YAAY,EAAgB,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAMzE;;;GAGG;AACH,MAAM,WAAW,4BAA6B,SAAQ,kCAAkC;IACtF;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IACrF,2DAA2D;IAC3D,kBAAkB,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,cAAc,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,uFAAuF;IACvF,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5H;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IACvF,uCAAuC;IACvC,aAAa,EAAE,IAAI,CAAC;IACpB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,kBAAkB,EAAE,4BAA4B,EAAE,CAAC;IACnD,4FAA4F;IAC5F,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE,0BAA0B,CAAC,OAAO,CAAC,CAAC,CAAC;CAClE;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU;IAC3E,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,4BAA4B,EAAE,CAAC;CAC1C;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,EACpE,MAAM,EAAE,+BAA+B,CAAC,OAAO,CAAC,GAC/C,4BAA4B,CAAC,OAAO,CAAC,CA0KvC"}

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

@@ -0,0 +1,267 @@
+/**
+ * Resource Polymorphism — Schema Declaration (Phase 1)
+ *
+ * Provides `declarePolymorphicSchemas()` which takes a base schema and a list
+ * of parent variant definitions, and produces a `PolymorphicSchemaDeclaration`
+ * containing pre-computed schemas for each variant (base + injected parent FK).
+ *
+ * Supports both plain `z.ZodObject` and `SchemaFamily` as base schema input.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md — Phase 1
+ */
+import { z } from 'zod';
+import { getZodObjectShape, addDiscriminator, getPolymorphicFkVariants } from '@wildo-ai/zod-decorators';
+import { ResourcePolymorphismUtils } from './resource-polymorphism.utils.js';
+// =============================================================================
+// TYPE GUARDS
+// =============================================================================
+/**
+ * Check if a value is a SchemaFamily (result of createSchemaFamily()).
+ * Duck-types on the presence of `.union`, `.base`, `.discriminatorField`.
+ */
+function isSchemaFamily(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return ('union' in obj &&
+        'base' in obj &&
+        'discriminatorField' in obj &&
+        'variants' in obj &&
+        'inheritenceSchemaDefinition' in obj);
+}
+/**
+ * Check if a schema is a ZodObject (has .shape).
+ */
+function isZodObject(schema) {
+    return schema instanceof z.ZodObject;
+}
+// =============================================================================
+// MAIN FUNCTION
+// =============================================================================
+/**
+ * Declare polymorphic schemas for a base resource.
+ *
+ * For each variant definition, this function:
+ * 1. Derives all naming identifiers using `ResourcePolymorphismUtils`
+ * 2. Clones the base schema and injects the parent's field identifier as a new FK field
+ * 3. If the base schema is a `SchemaFamily`, rebuilds the family per variant
+ * 4. Returns a `PolymorphicSchemaDeclaration` with pre-computed variants
+ *
+ * @example
+ * ```typescript
+ * // Plain z.ZodObject base:
+ * const billingDeclaration = declarePolymorphicSchemas({
+ *   baseResourceType: 'billingAccounts',
+ *   baseFieldIdentifier: 'billingAccountId',
+ *   baseEnumKey: 'BILLING_ACCOUNTS',
+ *   baseSchema: BillingAccountBaseSchema,
+ *   variants: [
+ *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },
+ *     { parentResourceType: 'users',         parentFieldIdentifier: 'userId',         isPrimaryScope: true },
+ *   ],
+ * });
+ *
+ * // SchemaFamily base:
+ * const subscriptionDeclaration = declarePolymorphicSchemas({
+ *   baseResourceType: 'subscriptions',
+ *   baseFieldIdentifier: 'subscriptionId',
+ *   baseEnumKey: 'SUBSCRIPTIONS',
+ *   baseSchema: SubscriptionSchemaFamily,  // result of createSchemaFamily()
+ *   variants: [
+ *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },
+ *   ],
+ * });
+ * ```
+ */
+export function declarePolymorphicSchemas(config) {
+    const { baseResourceType, baseFieldIdentifier, baseEnumKey, baseSchema, variants: variantDefinitions } = config;
+    // Validation: must have at least one variant
+    if (variantDefinitions.length === 0) {
+        throw new Error(`[PolymorphicSchemas] baseResourceType="${baseResourceType}": must have at least one variant definition.`);
+    }
+    // Validation: no duplicate parentResourceType
+    const parentTypes = variantDefinitions.map(v => v.parentResourceType);
+    const uniqueParentTypes = new Set(parentTypes);
+    if (uniqueParentTypes.size !== parentTypes.length) {
+        throw new Error(`[PolymorphicSchemas] baseResourceType="${baseResourceType}": duplicate parentResourceType in variant definitions.`);
+    }
+    // Derive naming for all variants
+    const namingKit = ResourcePolymorphismUtils.getVariants(baseResourceType, baseFieldIdentifier, baseEnumKey, variantDefinitions.map(v => ({ parentResourceType: v.parentResourceType, parentFieldIdentifier: v.parentFieldIdentifier })));
+    // Determine the root ZodObject to validate and extend
+    const rootZodObject = isSchemaFamily(baseSchema)
+        ? baseSchema.base
+        : isZodObject(baseSchema) ? baseSchema : null;
+    // Validation: base schema must be a ZodObject or SchemaFamily
+    if (!rootZodObject) {
+        throw new Error(`[PolymorphicSchemas] baseResourceType="${baseResourceType}": baseSchema must be a z.object() or a SchemaFamily (result of createSchemaFamily()). Got: ${typeof baseSchema}`);
+    }
+    // Validation: base schema should NOT already contain any of the parent FK fields
+    const baseShape = getZodObjectShape(rootZodObject);
+    for (const variantDef of variantDefinitions) {
+        if (baseShape[variantDef.parentFieldIdentifier]) {
+            throw new Error(`[PolymorphicSchemas] baseResourceType="${baseResourceType}": baseSchema already contains field "${variantDef.parentFieldIdentifier}". ` +
+                `The polymorphic declaration injects parent FK fields automatically — remove it from the base schema.`);
+        }
+    }
+    // Pre-compute polymorphic FK renames from the base schema.
+    // For each field in the base shape, check if it has `polymorphicVariants` metadata.
+    // If so, build a map: fieldName → { parentResourceType → derivedFieldName }.
+    const polymorphicFkRenames = computePolymorphicFkRenames(baseShape, variantDefinitions);
+    // Build the variants map
+    const variantsMap = new Map();
+    for (let i = 0; i < variantDefinitions.length; i++) {
+        const variantDef = variantDefinitions[i];
+        const naming = namingKit[i];
+        // Create the parent FK field: z.string().min(1).isForeignKey().isDBIndexed()
+        const parentFkField = z.string().min(1).isForeignKey().isDBIndexed();
+        // Compute FK renames for this specific variant
+        const fkRenamesForVariant = getFkRenamesForVariant(polymorphicFkRenames, variantDef.parentResourceType);
+        // Extend the schema with the parent FK field
+        let variantSchema;
+        let variantSchemaFamily;
+        if (isSchemaFamily(baseSchema)) {
+            const family = baseSchema;
+            // Extend the family's base schema with parent FK + apply FK renames
+            // Cast needed: Zod 4's .extend() returns ZodObject<Readonly<...>> which is stricter than ZodRawShape
+            let extendedBase = family.base.extend({
+                [variantDef.parentFieldIdentifier]: parentFkField,
+            });
+            extendedBase = applyFkRenames(extendedBase, fkRenamesForVariant);
+            // Rebuild each variant schema with the parent FK injected + FK renames
+            const extendedVariants = {};
+            for (const [key, variantSchemaEntry] of Object.entries(family.variants)) {
+                let extended = variantSchemaEntry.extend({
+                    [variantDef.parentFieldIdentifier]: parentFkField,
+                });
+                extended = applyFkRenames(extended, fkRenamesForVariant);
+                extendedVariants[key] = extended;
+            }
+            // Rebuild the discriminated union with parent FK in all branches
+            // Use addDiscriminator() to preserve isDiscriminator metadata (matching createSchemaFamily behavior)
+            const allUnionSchemas = [];
+            // Base value schemas (base + parent FK + decorated discriminator)
+            for (const baseValue of family.baseValues) {
+                const baseWithDiscriminator = extendedBase.extend({
+                    [family.discriminatorField]: addDiscriminator(z.literal(baseValue), { baseValues: family.baseValues }),
+                });
+                allUnionSchemas.push(baseWithDiscriminator);
+            }
+            // Extended variant schemas — re-decorate discriminator to ensure metadata is preserved
+            for (const [variantKey, extendedVariantSchema] of Object.entries(extendedVariants)) {
+                allUnionSchemas.push(extendedVariantSchema.extend({
+                    [family.discriminatorField]: addDiscriminator(z.literal(variantKey), { baseValues: family.baseValues }),
+                }));
+            }
+            // Create the union
+            let union;
+            if (allUnionSchemas.length >= 2) {
+                union = z.discriminatedUnion(family.discriminatorField, allUnionSchemas);
+            }
+            else if (allUnionSchemas.length === 1) {
+                union = allUnionSchemas[0];
+            }
+            else {
+                union = extendedBase;
+            }
+            // Build the rebuilt SchemaFamily for this variant
+            variantSchemaFamily = {
+                base: extendedBase,
+                discriminatorField: family.discriminatorField,
+                baseValues: family.baseValues,
+                variants: extendedVariants,
+                union,
+                inheritenceSchemaDefinition: family.inheritenceSchemaDefinition,
+            };
+            // The main schema for the resource config is the union
+            variantSchema = union;
+        }
+        else {
+            // Plain ZodObject — simple extend + FK renames
+            let extended = rootZodObject.extend({
+                [variantDef.parentFieldIdentifier]: parentFkField,
+            });
+            extended = applyFkRenames(extended, fkRenamesForVariant);
+            variantSchema = extended;
+        }
+        variantsMap.set(variantDef.parentResourceType, {
+            parentResourceType: variantDef.parentResourceType,
+            parentFieldIdentifier: variantDef.parentFieldIdentifier,
+            isPrimaryScope: variantDef.isPrimaryScope,
+            resourceType: naming.resourceType,
+            fieldIdentifier: naming.fieldIdentifier,
+            collectionName: naming.collectionName,
+            routeSegment: naming.routeSegment,
+            enumKey: naming.enumKey,
+            schema: variantSchema,
+            ...(variantSchemaFamily ? { schemaFamily: variantSchemaFamily } : {}),
+        });
+    }
+    return {
+        __polymorphic: true,
+        baseResourceType,
+        baseFieldIdentifier,
+        baseEnumKey,
+        baseSchema,
+        variantDefinitions,
+        variants: variantsMap,
+    };
+}
+/**
+ * Scan the base schema shape for fields with `polymorphicVariants` metadata.
+ * Build a rename map: originalFieldName → { parentResourceType → derivedFieldName }.
+ */
+function computePolymorphicFkRenames(baseShape, variantDefinitions) {
+    const renames = new Map();
+    for (const [fieldName, fieldSchema] of Object.entries(baseShape)) {
+        const fkVariants = getPolymorphicFkVariants(fieldSchema);
+        if (!fkVariants || fkVariants.length === 0)
+            continue;
+        const fieldRenames = new Map();
+        for (const variantDef of variantDefinitions) {
+            const matchingFkVariant = fkVariants.find(fkv => fkv.parentResourceType === variantDef.parentResourceType);
+            if (matchingFkVariant) {
+                const derivedName = ResourcePolymorphismUtils.deriveVariantFieldIdentifier(matchingFkVariant.parentFieldIdentifier, fieldName);
+                fieldRenames.set(variantDef.parentResourceType, derivedName);
+            }
+        }
+        if (fieldRenames.size > 0) {
+            renames.set(fieldName, fieldRenames);
+        }
+    }
+    return renames;
+}
+/**
+ * Get the FK renames applicable for a specific parent resource type.
+ * Returns an array of [originalFieldName, derivedFieldName] pairs.
+ */
+function getFkRenamesForVariant(renameMap, parentResourceType) {
+    const result = [];
+    for (const [originalName, perParent] of renameMap) {
+        const derived = perParent.get(parentResourceType);
+        if (derived) {
+            result.push([originalName, derived]);
+        }
+    }
+    return result;
+}
+/**
+ * Apply FK renames to a ZodObject: remove original field, add derived field with same schema.
+ */
+function applyFkRenames(schema, renames) {
+    if (renames.length === 0)
+        return schema;
+    // Cast to mutable shape — getZodObjectShape may return Readonly in Zod 4
+    const shape = getZodObjectShape(schema);
+    const newShape = {};
+    for (const [key, value] of Object.entries(shape)) {
+        const rename = renames.find(([orig]) => orig === key);
+        if (rename) {
+            newShape[rename[1]] = value;
+        }
+        else {
+            newShape[key] = value;
+        }
+    }
+    return z.object(newShape);
+}
+//# sourceMappingURL=resource-polymorphism.schemas.js.map