@wildo-ai/saas-models 1.0.1

package/dist/esm/resources/utils/resources-config-operations.urls-builder.utils.d.ts

@@ -0,0 +1,258 @@
+/** URL Generation Examples:
+ *
+ * Collection-Level Operations (no entity ID):
+ * - LIST: GET /api/v1/organizations/{organizationId}/organization-features
+ * - CREATE: POST /api/v1/organizations/{organizationId}/organization-features
+ * - CREATE_MANY: POST /api/v1/organizations/{organizationId}/organization-features (differentiated by request body)
+ * - UPDATE_MANY: PUT /api/v1/organizations/{organizationId}/organization-features
+ * - DELETE_MANY: DELETE /api/v1/organizations/{organizationId}/organization-features
+ * - SEARCH: GET /api/v1/organizations/{organizationId}/organization-features/search
+ * - COUNT: GET /api/v1/organizations/{organizationId}/organization-features/count
+ * - Custom collection operations (with resourceOperationLike pointing to collection op):
+ *   PUT /api/v1/organizations/{organizationId}/organization-features/reset-features
+ *
+ * Entity-Level Operations (with entity ID):
+ * - READ: GET /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}
+ * - UPDATE: PUT /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}
+ * - DELETE: DELETE /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}
+ * - Custom entity operations (with resourceOperationLike pointing to entity op):
+ *   PUT /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}/enable-feature
+ *
+ * Variant Keys (for role-based variants):
+ * - LIST admin variant: GET /api/v1/organizations/{organizationId}/organization-features/admin
+ * - READ admin variant: GET /api/v1/organizations/{organizationId}/organization-features/{id}/admin
+ * - SEARCH admin variant: GET /api/v1/organizations/{organizationId}/organization-features/search/admin
+ *
+ * Bulk Operations (collection-level, no entity ID):
+ * - DELETE bulk: DELETE /api/v1/organizations/{organizationId}/organization-features/bulk
+ * - DELETE bulk admin: DELETE /api/v1/organizations/{organizationId}/organization-features/bulk/admin
+ *
+ * Access Scope Strategy (determines URL path generation):
+ * - REQUIRES_CONTEXT: Always in URL path (mandatory parent)
+ * - OPTIONAL_CONTEXT: Generates multiple URLs with/without parent
+ * - STANDALONE: NEVER in URL path - resource accessed independently (data relationship only)
+ *   Example: APPLICATION → ORGANIZATIONS with STANDALONE means /organizations not /applications/{id}/organizations
+ *
+ * Foreign Key Relationships (foreignKeyField):
+ * - FK relationships like TODOS → USERS with assignedToUserId are transformed to parent relationships
+ * - They use OPTIONAL_CONTEXT to generate alternative URL paths
+ * - Example: /assigned-to-users/{assignedToUserId}/todos (prefix derived from FK field name)
+ *
+ * Many-to-Many Relationships (via junction table):
+ * - Junction table (e.g., ORGANIZATION_MEMBERS) can be accessed from BOTH sides
+ * - Both parents use OPTIONAL_CONTEXT to generate independent paths
+ * - Example: /organizations/{orgId}/organization-members
+ * - Example: /users/{userId}/organization-members
+ * - Combined: /organizations/{orgId}/users/{userId}/organization-member (singular, unique record)
+ */
+import { AnyResourceConfiguration, ResourceConfiguration_Operation_ApiCall, ResourceConfiguration_Operation_ApiCallWithCallback, ResourceConfiguration_Operation_UrlParameterInfo, ResourceConfiguration_Operation_UrlInitiatorInfo } from '../resources-config.shared.schemas.js';
+import { z } from 'zod';
+import { ResourceRelationship, ResourceRelationshipAccessScopeStrategy, ResourceRelationshipCardinality } from '../resources.shared.schemas.js';
+import { ResourceType, ResourceFieldIdentifier, CoreResourceOperation } from '../resources.shared.core.definitions.js';
+import { EnumLikeType } from '@wildo-ai/zod-decorators';
+export interface URLGenerationResult {
+    initiatorInfos: ResourceConfiguration_Operation_UrlInitiatorInfo[];
+    metadata: {
+        operation: string;
+        variantKey?: string;
+        isBulk: boolean;
+        isSearch: boolean;
+        isCount: boolean;
+        parentCombinations: string[][];
+    };
+}
+export interface ParentResourceInfo {
+    resourceType: ResourceType;
+    fieldIdentifier: string;
+    isPrimaryScope: boolean;
+    isOptional: boolean;
+    accessScopeStrategy: ResourceRelationshipAccessScopeStrategy;
+    /** Foreign key field for disambiguation or non-standard naming */
+    foreignKeyField?: string;
+    cardinality2: ResourceRelationshipCardinality;
+    order: number;
+}
+export type ResourceConfiguration_Operation_Urlisable<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined> = ResourceConfiguration_Operation_ApiCall<TCustomOperationEnum, TCoreOperationEnum, z.ZodTypeAny> | ResourceConfiguration_Operation_ApiCallWithCallback<TCustomOperationEnum, TCoreOperationEnum, z.ZodTypeAny>;
+export declare class ResourcesConfigOperationsUrlsBuilderUtils {
+    static buildUrlsForResourceConfiguration(resourceConfig: AnyResourceConfiguration, allResourceFieldIdentifiers: Record<string, string>): Record<string, URLGenerationResult>;
+    /**
+    * Build URLs for all API_CALL and API_CALL_WITH_CALLBACK operations in a resource configuration
+    */
+    static updateOperationUrls(resourceConfig: AnyResourceConfiguration, allResourceFieldIdentifiers: Record<string, string>): void;
+    /**
+     * Return the full parent edge set that can legitimately address a resource in URLs.
+     *
+     * This includes:
+     * - real parent/self relationships from the compiled resource model
+     * - synthetic FK-reference parents used to expose alternative nested paths for
+     *   non-standard FK fields without polluting the stored relationship graph
+     *
+     * Frontend navigation and form/runtime consumers should reuse this helper when
+     * they need to stay aligned with URL addressability semantics.
+     */
+    static getUrlAddressableParentRelationships(resourceConfig: AnyResourceConfiguration, allResourceFieldIdentifiers: Record<string, string>): ResourceRelationship[];
+    /**
+     * Build URLs for a specific operation
+     */
+    private static buildUrlsForOperation;
+    static buildOperationFrontendRoutePaths(resourceConfig: AnyResourceConfiguration, operation: ResourceConfiguration_Operation_Urlisable<any, any>, allResourceFieldIdentifiers: Record<string, string>): {
+        url: string;
+        parameters: ResourceConfiguration_Operation_UrlParameterInfo[];
+    }[];
+    /**
+     * Build a resource-integrated file upload route from a concrete operation route.
+     *
+     * File uploads should stay aligned with the operation route family they extend.
+     * For CREATE-like uploads, the collection route is sufficient. For UPDATE-like
+     * uploads, the target resource id must appear exactly once:
+     * - if the operation route already addresses the entity, reuse it as-is
+     * - if the operation route intentionally omits the entity id (for unique nested
+     *   addresses such as one-to-one or complete many-to-many paths), append the
+     *   target resource placeholder before the `/files/:field` suffix
+     *
+     * The returned `parameters` array mirrors the final route shape so backend
+     * request-context extraction and frontend placeholder resolution stay in sync.
+     */
+    static buildFileUploadRouteForOperation(params: {
+        operationRouteUrl: string;
+        operationParameters: ResourceConfiguration_Operation_UrlParameterInfo[];
+        targetResourceType: ResourceType;
+        targetResourceFieldIdentifier: ResourceFieldIdentifier;
+        fieldName: string;
+        requiresTargetResourceId: boolean;
+        isFrontend: boolean;
+    }): {
+        url: string;
+        parameters: ResourceConfiguration_Operation_UrlParameterInfo[];
+    };
+    /**
+   * Build URL for a specific parent combination
+   *
+   * When a parent has a foreignKeyField (like assignedToUserId), the prefix
+   * is applied to the PARENT resource name, not the child:
+   * - /assigned-to-users/{assignedToUserId}/todos (prefix on parent)
+   * - NOT /users/{userId}/assigned-to-todos (prefix on child)
+   */
+    static buildUrlForParentCombination(parentCombo: ParentResourceInfo[], resourceConfig: AnyResourceConfiguration, operation: ResourceConfiguration_Operation_Urlisable<any, any>, allResourceFieldIdentifiers: Record<string, string>, isFrontend?: boolean): {
+        url: string;
+        parameters: ResourceConfiguration_Operation_UrlParameterInfo[];
+    };
+    /**
+     * Get parent resource information with ordering
+     */
+    static getParentResourceInfos(parentRelationships: ResourceRelationship[], allResourceFieldIdentifiers: Record<string, string>): ParentResourceInfo[];
+    /**
+     * Order parent resources by dependency chain and alphabetically
+     */
+    private static orderParentResourceInfos;
+    /**
+     * Generate all possible parent combinations based on accessScopeStrategy
+     *
+     * Access Scope Strategy Rules:
+     * - REQUIRES_CONTEXT: Always included in parent context (mandatory in URL path)
+     * - OPTIONAL_CONTEXT: Can be included or not in parent context (generates multiple URL paths)
+     * - STANDALONE: Never included in URL path - resource is accessed independently
+     *   (the relationship exists for data model purposes, but not for URL routing)
+     */
+    private static generateParentCombinations;
+    /**
+     * Generate all possible combinations of optional items
+     */
+    private static generateOptionalCombinations;
+    /**
+     * Get operation-specific URL segments
+     *
+     * URL Pattern Rules:
+     * - Core collection operations (LIST, CREATE, etc.): No operation suffix, differentiated by HTTP method
+     * - SEARCH: /search suffix (single occurrence)
+     * - COUNT: /count suffix (single occurrence)
+     * - Custom collection operations: Add operation name (e.g., /reset-features)
+     * - Core entity operations (READ, UPDATE, DELETE): No suffix after entity ID
+     * - Custom entity operations: Add operation name after entity ID (e.g., /{id}/rotate)
+     */
+    private static getOperationSegments;
+    /**
+     * Generate main resource path segment
+     *
+     * Note: The relationship prefix (like "assigned-to") is now applied to the PARENT resource
+     * in buildUrlForParentCombination, not to the child resource here.
+     *
+     * Examples:
+     * - /assigned-to-users/{userId}/todos (prefix on parent "users")
+     * - /created-by-users/{userId}/todos (prefix on parent "users")
+     * - /organizations/{orgId}/todos (no relationship field, no prefix)
+     * - /organizations/{orgId}/organization-preference (singular for one-to-one)
+     * - /organizations/{orgId}/users/{userId}/organization-member (singular for complete many-to-many)
+     */
+    private static generateMainResourcePath;
+    /**
+     * Extract relationship prefix from a relationship field, excluding the parent resource type.
+     *
+     * Pattern: {relationshipDescriptor}{ParentResourceType}Id
+     * - assignedToUserId with parentType=users → assignedTo → assigned-to
+     * - createdByUserId with parentType=users → createdBy → created-by
+     *
+     * @param relationshipField - The relationship field name (e.g., assignedToUserId)
+     * @param parentResourceType - The parent resource type (e.g., users) - optional, if provided will be stripped
+     */
+    static extractRelationshipPrefix(relationshipField: string, parentResourceType?: ResourceType): string;
+    private static getOperationKey;
+    private static getCoreOperation;
+    private static isUrlisable;
+    /**
+   * Determines if an operation should be at collection level (no entity ID) or entity level
+   *
+   * Collection-level operations include:
+   * - Core collection operations (LIST, CREATE, CREATE_MANY, UPDATE_MANY, DELETE_MANY, SEARCH, COUNT)
+   * - Custom operations with resourceOperationLike pointing to a collection operation
+   * - Bulk operations (isBulkOperation = true) - they operate on multiple entities
+   */
+    private static isCollectionLevelOperation;
+    /**
+     * Check if this resource has a one-to-one relationship with its parent
+     * Used to determine if resource should use singular naming and no entity ID
+     */
+    private static isOneToOneRelationship;
+    /**
+     * Check if this represents a complete many-to-many path (both entities specified)
+     * For junction tables, when both foreign keys are specified in the path,
+     * there can only be one matching record, so we use singular form and no entity ID
+     *
+     * Example: /organizations/{orgId}/users/{userId}/organization-member
+     * This uniquely identifies THE membership between this org and user
+     *
+     * Important: This should NOT match hierarchical relationships with optional parents.
+     * For example, todos with optional todoList parent is NOT a junction table.
+     * Junction tables require BOTH parents to be required (REQUIRES_CONTEXT or isPrimaryScope).
+     */
+    private static isCompleteManyToManyPath;
+    /**
+     * Generate synthetic parent relationships for FK reference URL paths.
+     *
+     * These synthetic relationships are created ON-THE-FLY during URL generation
+     * and do NOT pollute the data model's parentRelationships.
+     *
+     * Purpose: Enable alternative URL access patterns for resources with non-standard FK fields.
+     * Example: TODOS → USERS with 'assignedToUserId' creates /assigned-to-users/{userId}/todos
+     *
+     * This method replaces the FK transformation that was previously done in the factory,
+     * which incorrectly modified the relationship model and broke context fetching/population.
+     *
+     * Edge Cases Handled:
+     * - M:N relationships: Excluded (not in childRelationships)
+     * - Self-referencing: Filtered out (line 781)
+     * - Missing standard FK: Skipped gracefully (line 785-787)
+     * - Standard FK (e.g., USER_SELF with userId): Correctly identified and skipped (line 793-795)
+     *
+     * Known Minor Inefficiency:
+     * - Multiple non-standard FKs to same resource type (e.g., assignedToUserId + createdByUserId)
+     *   creates extra URL combinations including both FKs in one path.
+     *   Not harmful, just generates unused URL patterns. Can be optimized later.
+     *
+     * @param resourceConfig - Resource configuration with clean relationship model
+     * @param allResourceFieldIdentifiers - Map of resourceType → standard field identifier
+     * @returns Array of synthetic parent relationships (for URL generation ONLY)
+     */
+    private static generateSyntheticFKParents;
+}
+//# sourceMappingURL=resources-config-operations.urls-builder.utils.d.ts.map

package/dist/esm/resources/utils/resources-config-operations.urls-builder.utils.d.ts.map

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