@wildo-ai/saas-models 1.0.1

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

@@ -0,0 +1,693 @@
+/** 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 { getParentDirectionRelationships, getChildDirectionRelationships, } from '../resources-config.shared.schemas.js';
+import { RelationshipNature, ResourceParentResourceRequirement, ResourceOperationVariantType, ResourceRelationshipAccessScopeStrategy, isOneToOneCardinality } from '../resources.shared.schemas.js';
+import { ALL_COLLECTION_OPERATIONS, CoreResourceOperation } from '../resources.shared.core.definitions.js';
+import { ResourcesConfigNamingUtils } from './resources-config-naming.utils.js';
+import { Resources_SharedUtils } from '../resources.shared.utils.js';
+import { ResourcesConfig_OperationPathUtils } from './resources-config-operations.path.utils.js';
+export class ResourcesConfigOperationsUrlsBuilderUtils {
+    static buildUrlsForResourceConfiguration(resourceConfig, allResourceFieldIdentifiers) {
+        const results = {};
+        const apiCallOperations = resourceConfig.operations.filter((op) => this.isUrlisable(op.variantType));
+        for (const operation of apiCallOperations) {
+            const operationKey = this.getOperationKey(operation);
+            results[operationKey] = this.buildUrlsForOperation(operation, resourceConfig, allResourceFieldIdentifiers);
+        }
+        return results;
+    }
+    /**
+    * Build URLs for all API_CALL and API_CALL_WITH_CALLBACK operations in a resource configuration
+    */
+    static updateOperationUrls(resourceConfig, allResourceFieldIdentifiers) {
+        const urlResults = this.buildUrlsForResourceConfiguration(resourceConfig, allResourceFieldIdentifiers);
+        // Update URLs in API_CALL and API_CALL_WITH_CALLBACK operations
+        for (const operation of resourceConfig.operations) {
+            if (this.isUrlisable(operation.variantType)) {
+                const apiCallOp = operation;
+                const operationKey = this.getOperationKey(apiCallOp);
+                const urlResult = urlResults[operationKey];
+                if (urlResult) {
+                    apiCallOp.initiatorInfos = urlResult.initiatorInfos;
+                }
+            }
+        }
+    }
+    /**
+     * 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, allResourceFieldIdentifiers) {
+        const realParents = getParentDirectionRelationships(resourceConfig.resourceRelationships);
+        const syntheticFKParents = this.generateSyntheticFKParents(resourceConfig, allResourceFieldIdentifiers);
+        return [...realParents, ...syntheticFKParents];
+    }
+    /**
+     * Build URLs for a specific operation
+     */
+    static buildUrlsForOperation(operation, resourceConfig, allResourceFieldIdentifiers) {
+        const initiatorInfos = [];
+        const allParentsForURLs = this.getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers);
+        // Generate URL paths from all parent combinations
+        const parentInfos = this.getParentResourceInfos(allParentsForURLs, allResourceFieldIdentifiers);
+        const parentCombinations = this.generateParentCombinations(parentInfos);
+        const coreOperation = this.getCoreOperation(operation);
+        for (const parentCombo of parentCombinations) {
+            const urlInfo = this.buildUrlForParentCombination(parentCombo, resourceConfig, operation, allResourceFieldIdentifiers, false);
+            const initiatorInfo = {
+                url: urlInfo.url,
+                parameters: urlInfo.parameters,
+                ...(operation.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK && {
+                    urlCallback: `${urlInfo.url}/callback`
+                })
+            };
+            initiatorInfos.push(initiatorInfo);
+        }
+        // W7.3a: Dual initiatorInfos for isAnonymizable resources.
+        // For operations that allow APP_ANONYMOUS, generate additional URL patterns
+        // with the ANONYMOUS_USERS parent replacing the USER_SELF parent.
+        if (resourceConfig.isAnonymizable && operation.roles?.includes('APP_ANONYMOUS')) {
+            for (const parentCombo of parentCombinations) {
+                const userSelfParentIndex = parentCombo.findIndex(p => p.isPrimaryScope && p.fieldIdentifier === 'userId');
+                if (userSelfParentIndex >= 0) {
+                    const anonymousCombo = parentCombo.map((p, i) => {
+                        if (i === userSelfParentIndex) {
+                            return {
+                                ...p,
+                                resourceType: 'anonymous_users',
+                                fieldIdentifier: 'anonymousUserId',
+                            };
+                        }
+                        return p;
+                    });
+                    const urlInfo = this.buildUrlForParentCombination(anonymousCombo, resourceConfig, operation, allResourceFieldIdentifiers, false);
+                    const anonInitiatorInfo = {
+                        url: urlInfo.url,
+                        parameters: urlInfo.parameters,
+                        ...(operation.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK && {
+                            urlCallback: `${urlInfo.url}/callback`
+                        })
+                    };
+                    initiatorInfos.push(anonInitiatorInfo);
+                }
+            }
+        }
+        return {
+            initiatorInfos,
+            metadata: {
+                operation: String(operation.operationIdentifier),
+                variantKey: operation.variantKey,
+                isBulk: operation.isBulkOperation,
+                isCount: coreOperation === CoreResourceOperation.COUNT,
+                isSearch: coreOperation === CoreResourceOperation.SEARCH,
+                parentCombinations: parentCombinations.map(combo => combo.map(parent => parent.resourceType))
+            }
+        };
+    }
+    static buildOperationFrontendRoutePaths(resourceConfig, operation, allResourceFieldIdentifiers) {
+        if (!this.isUrlisable(operation.variantType))
+            return []; // other presets are not routable
+        const allParentsForURLs = this.getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers);
+        const parentInfos = this.getParentResourceInfos(allParentsForURLs, allResourceFieldIdentifiers);
+        const parentCombinations = this.generateParentCombinations(parentInfos);
+        const frontendRoutePaths = [];
+        for (const parentCombo of parentCombinations) {
+            const routePath = this.buildUrlForParentCombination(parentCombo, resourceConfig, operation, allResourceFieldIdentifiers, true);
+            frontendRoutePaths.push(routePath);
+        }
+        return frontendRoutePaths;
+    }
+    /**
+     * 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) {
+        const parameters = [...params.operationParameters];
+        const hasTargetResourceIdParameter = parameters.some((parameter) => parameter.fieldIdentifier === params.targetResourceFieldIdentifier);
+        let url = params.operationRouteUrl;
+        if (params.requiresTargetResourceId && !hasTargetResourceIdParameter) {
+            const targetPlaceholder = params.isFrontend
+                ? `:${params.targetResourceFieldIdentifier}`
+                : `{${params.targetResourceFieldIdentifier}}`;
+            url = `${url}/${targetPlaceholder}`;
+            parameters.push({
+                fieldIdentifier: params.targetResourceFieldIdentifier,
+                resourceType: params.targetResourceType,
+            });
+        }
+        return {
+            url: `${url}/files/${params.fieldName}`,
+            parameters,
+        };
+    }
+    // ===========================================================================================
+    // PARENT RELATIONSHIP MANAGEMENT
+    // =========================================================================================
+    /**
+   * 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, resourceConfig, operation, allResourceFieldIdentifiers, isFrontend = false) {
+        const segments = !isFrontend ? ['/api/v1'] : [];
+        const parameters = [];
+        // For frontend routes (React Router), use :paramName format
+        // For backend routes (Express), use {paramName} format
+        const formatParam = (paramName) => isFrontend ? `:${paramName}` : `{${paramName}}`;
+        // Add parent resource segments
+        for (const parent of parentCombo) {
+            let resourcePath = ResourcesConfigNamingUtils.toKebabCase(parent.resourceType);
+            // For FK relationships, use the FK field as the parameter name (e.g., assignedToUserId)
+            // For standard relationships, use the standard field identifier (e.g., userId)
+            // This avoids confusion and makes URLs self-documenting
+            const parameterName = parent.foreignKeyField || parent.fieldIdentifier;
+            // If parent has a foreignKeyField, apply the prefix to the parent resource name
+            // Example: assignedToUserId with parent=users → "assigned-to-users" instead of just "users"
+            if (parent.foreignKeyField) {
+                const relationshipPrefix = this.extractRelationshipPrefix(parent.foreignKeyField, parent.resourceType);
+                if (relationshipPrefix) {
+                    resourcePath = `${relationshipPrefix}-${resourcePath}`;
+                }
+            }
+            segments.push(resourcePath);
+            segments.push(formatParam(parameterName));
+            parameters.push({
+                fieldIdentifier: parameterName,
+                resourceType: parent.resourceType,
+                relationshipField: parent.foreignKeyField,
+            });
+        }
+        // Add main resource segment (no longer modified by relationship context - prefix is on parent)
+        const mainResourcePath = this.generateMainResourcePath(resourceConfig.resourceIdentifier, parentCombo);
+        segments.push(mainResourcePath);
+        // Add operation-specific segments
+        const operationSegments = this.getOperationSegments(operation, resourceConfig, allResourceFieldIdentifiers, parentCombo, isFrontend);
+        segments.push(...operationSegments.segments);
+        parameters.push(...operationSegments.parameterInfos);
+        const prefix = isFrontend ? '/' : '';
+        return {
+            url: prefix + segments.join('/').replace(/\/+/g, '/'),
+            parameters
+        };
+    }
+    /**
+     * Get parent resource information with ordering
+     */
+    static getParentResourceInfos(parentRelationships, allResourceFieldIdentifiers) {
+        const parentInfos = [];
+        for (const relationship of parentRelationships) {
+            const resourceType = relationship.resourceType1;
+            const fieldIdentifier = allResourceFieldIdentifiers[resourceType];
+            parentInfos.push({
+                resourceType,
+                fieldIdentifier,
+                isPrimaryScope: relationship.isPrimaryScope || false,
+                isOptional: relationship.parentResourceRequirement === ResourceParentResourceRequirement.OPTIONAL,
+                accessScopeStrategy: relationship.accessScopeStrategy,
+                foreignKeyField: relationship.foreignKeyField,
+                cardinality2: relationship.cardinality2,
+                order: 0 // Will be calculated later
+            });
+        }
+        // Order by dependency chain, then alphabetically
+        return this.orderParentResourceInfos(parentInfos, parentRelationships);
+    }
+    /**
+     * Order parent resources by dependency chain and alphabetically
+     */
+    static orderParentResourceInfos(parentInfos, allRelationships) {
+        // Create dependency map
+        const dependencyMap = new Map();
+        for (const info of parentInfos) {
+            dependencyMap.set(info.resourceType, new Set());
+        }
+        // Build dependency chains
+        for (const relationship of allRelationships) {
+            if (dependencyMap.has(relationship.resourceType2) &&
+                dependencyMap.has(relationship.resourceType1)) {
+                dependencyMap.get(relationship.resourceType2).add(relationship.resourceType1);
+            }
+        }
+        // Topological sort with primary scope priority
+        const sorted = [];
+        const visited = new Set();
+        const visiting = new Set();
+        const visit = (info) => {
+            if (visiting.has(info.resourceType)) {
+                // Circular dependency, sort alphabetically
+                return;
+            }
+            if (visited.has(info.resourceType)) {
+                return;
+            }
+            visiting.add(info.resourceType);
+            // Visit dependencies first
+            const dependencies = dependencyMap.get(info.resourceType) || new Set();
+            const depInfos = parentInfos.filter(p => dependencies.has(p.resourceType));
+            depInfos.sort((a, b) => a.resourceType.localeCompare(b.resourceType));
+            for (const depInfo of depInfos) {
+                visit(depInfo);
+            }
+            visiting.delete(info.resourceType);
+            visited.add(info.resourceType);
+            sorted.push(info);
+        };
+        // Sort by priority: primary scope first, then alphabetically
+        const sortedInfos = [...parentInfos].sort((a, b) => {
+            if (a.isPrimaryScope && !b.isPrimaryScope)
+                return -1;
+            if (!a.isPrimaryScope && b.isPrimaryScope)
+                return 1;
+            return a.resourceType.localeCompare(b.resourceType);
+        });
+        for (const info of sortedInfos) {
+            visit(info);
+        }
+        return sorted;
+    }
+    /**
+     * 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)
+     */
+    static generateParentCombinations(parentInfos) {
+        // Filter out STANDALONE relationships - they are NEVER included in URL paths
+        const urlParents = parentInfos.filter(p => p.accessScopeStrategy !== ResourceRelationshipAccessScopeStrategy.STANDALONE);
+        const primaryScope = urlParents.filter(p => p.isPrimaryScope);
+        const mandatoryContext = urlParents.filter(p => !p.isPrimaryScope &&
+            p.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT);
+        // OPTIONAL_CONTEXT generates optional URL paths (with and without parent)
+        const optionalContext = urlParents.filter(p => p.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT &&
+            !p.isPrimaryScope);
+        // Generate all combinations of optional context parents
+        const optionalCombinations = this.generateOptionalCombinations(optionalContext);
+        const allCombinations = [];
+        for (const optionalCombo of optionalCombinations) {
+            const combination = [...primaryScope, ...mandatoryContext, ...optionalCombo];
+            if (combination.length > 0) {
+                allCombinations.push(combination);
+            }
+        }
+        // If no combinations, at least return empty combination
+        if (allCombinations.length === 0) {
+            allCombinations.push([]);
+        }
+        return allCombinations;
+    }
+    /**
+     * Generate all possible combinations of optional items
+     */
+    static generateOptionalCombinations(optionalItems) {
+        const combinations = [[]]; // Start with empty combination
+        for (const item of optionalItems) {
+            const currentLength = combinations.length;
+            for (let i = 0; i < currentLength; i++) {
+                combinations.push([...combinations[i], item]);
+            }
+        }
+        return combinations;
+    }
+    /**
+     * 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)
+     */
+    static getOperationSegments(operation, resourceConfig, allResourceFieldIdentifiers, parentCombo, isFrontend = false) {
+        const segments = [];
+        const parameterInfos = [];
+        const operationName = String(operation.operationIdentifier);
+        const isCollectionLevelOperation = this.isCollectionLevelOperation(operation, operationName);
+        // For frontend routes (React Router), use :paramName format
+        // For backend routes (Express), use {paramName} format
+        const formatParam = (paramName) => isFrontend ? `:${paramName}` : `{${paramName}}`;
+        // Determine if this is a custom operation (not a core operation)
+        const isCustomOperation = !Object.values(CoreResourceOperation).includes(operationName);
+        if (isCollectionLevelOperation) {
+            // For custom collection operations, add the operation name segment
+            if (isCustomOperation) {
+                const operationSegment = ResourcesConfigNamingUtils.toKebabCase(operationName);
+                segments.push(operationSegment);
+            }
+            // Core collection operations (LIST, CREATE, etc.) don't add operation name
+            // They differentiate by HTTP method (GET for LIST, POST for CREATE, etc.)
+        }
+        else {
+            // Entity-level operations
+            // Skip resource ID when the parent combination uniquely identifies the resource:
+            // - One-to-one: only one instance per parent (e.g., organization-preference)
+            // - Complete many-to-many: both foreign keys specified (e.g., org + user = unique membership)
+            if (!this.isOneToOneRelationship(parentCombo) && !this.isCompleteManyToManyPath(parentCombo)) {
+                const resourceParam = allResourceFieldIdentifiers[resourceConfig.resourceIdentifier];
+                segments.push(formatParam(resourceParam));
+                parameterInfos.push({
+                    fieldIdentifier: resourceParam,
+                    resourceType: resourceConfig.resourceIdentifier
+                });
+            }
+            // For custom entity operations, add the operation name after the entity ID
+            if (isCustomOperation) {
+                const operationSegment = ResourcesConfigNamingUtils.toKebabCase(operationName);
+                segments.push(operationSegment);
+            }
+        }
+        // Add bulk suffix if needed
+        if (operation.isBulkOperation) {
+            segments.push('bulk');
+        }
+        const coreOperation = this.getCoreOperation(operation);
+        // Add search segment when the operation carries SEARCH semantics.
+        if (coreOperation === CoreResourceOperation.SEARCH) {
+            segments.push('search');
+        }
+        // Add count segment when the operation carries COUNT semantics.
+        if (coreOperation === CoreResourceOperation.COUNT) {
+            segments.push('count');
+        }
+        // Add variant key if exists
+        if (operation.variantKey) {
+            segments.push(operation.variantKey);
+        }
+        return { segments, parameterInfos };
+    }
+    /**
+     * 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)
+     */
+    static generateMainResourcePath(mainResourceIdentifier, parentCombo) {
+        // Check if this is a one-to-one relationship OR a complete many-to-many path - use singular form
+        const baseResourcePath = (this.isOneToOneRelationship(parentCombo) || this.isCompleteManyToManyPath(parentCombo))
+            ? ResourcesConfigNamingUtils.toKebabCase(ResourcesConfigNamingUtils.singularize(mainResourceIdentifier))
+            : ResourcesConfigNamingUtils.toKebabCase(mainResourceIdentifier);
+        return baseResourcePath;
+    }
+    /**
+     * 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, parentResourceType) {
+        // Get base name without Id/Ids suffix
+        let baseName = ResourcesConfigNamingUtils.extractBaseName(relationshipField);
+        // If parent resource type is provided, remove it from the end of base name
+        // e.g., "assignedToUser" with parent "users" → "assignedTo"
+        if (parentResourceType) {
+            // Get singular form of parent resource type (e.g., "users" → "user")
+            const parentSingular = ResourcesConfigNamingUtils.singularize(parentResourceType);
+            // Capitalize first letter to match camelCase pattern (e.g., "user" → "User")
+            const parentSingularCapitalized = parentSingular.charAt(0).toUpperCase() + parentSingular.slice(1);
+            // Remove parent resource type from the end if present
+            // Check both capitalized form (e.g., "assignedToUser" ends with "User")
+            // and exact match (e.g., "user" ends with "User" when lowercased)
+            if (baseName.endsWith(parentSingularCapitalized)) {
+                baseName = baseName.slice(0, -parentSingularCapitalized.length);
+            }
+            else if (baseName.toLowerCase() === parentSingular.toLowerCase()) {
+                // Exact match for standard FK (e.g., "user" matches parent "users")
+                baseName = '';
+            }
+        }
+        // If baseName is empty after stripping, return empty (no prefix needed)
+        if (!baseName)
+            return '';
+        return ResourcesConfigNamingUtils.toKebabCase(baseName);
+    }
+    static getOperationKey(operation) {
+        return ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation);
+    }
+    static getCoreOperation(operation) {
+        if (operation.resourceOperationLike) {
+            return operation.resourceOperationLike;
+        }
+        else {
+            return operation.operationIdentifier;
+        }
+    }
+    // ================================
+    // CHECK HELPERS
+    // ================================
+    static isUrlisable(variantType) {
+        return variantType === ResourceOperationVariantType.API_CALL || variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
+    }
+    /**
+   * 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
+   */
+    static isCollectionLevelOperation(operation, operationName) {
+        // Bulk operations are always collection-level (no entity ID)
+        if (operation.isBulkOperation) {
+            return true;
+        }
+        if (ALL_COLLECTION_OPERATIONS.includes(operationName)) {
+            return true;
+        }
+        if (operation.resourceOperationLike) {
+            const resourceOperationLikeName = String(operation.resourceOperationLike);
+            if (ALL_COLLECTION_OPERATIONS.includes(resourceOperationLikeName)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * 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
+     */
+    static isOneToOneRelationship(parentCombo) {
+        // Check for one-to-one relationships in any of these scenarios:
+        // 1. Exactly one primary scope parent with ONE cardinality
+        // 2. Exactly one parent (any scope) with ONE cardinality
+        if (parentCombo.length === 1) {
+            const parent = parentCombo[0];
+            // Check if the cardinality from parent to child is 1:1 (ONE or ZERO_OR_ONE)
+            return isOneToOneCardinality(parent.cardinality2);
+        }
+        return false;
+    }
+    /**
+     * 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).
+     */
+    static isCompleteManyToManyPath(parentCombo) {
+        // For a complete many-to-many path, we need:
+        // 1. Exactly 2 parents 
+        // 2. One with primary scope (e.g., organization)
+        // 3. One without primary scope (e.g., user)
+        // 4. BOTH parents must be required (not OPTIONAL_CONTEXT)
+        //    - Primary scope parents are always required
+        //    - Non-primary scope parents must have REQUIRES_CONTEXT
+        if (parentCombo.length === 2) {
+            const primaryScopeParents = parentCombo.filter(parent => parent.isPrimaryScope);
+            const nonPrimaryScopeParents = parentCombo.filter(parent => !parent.isPrimaryScope);
+            // Must have exactly one primary and one non-primary scope parent
+            if (primaryScopeParents.length !== 1 || nonPrimaryScopeParents.length !== 1) {
+                return false;
+            }
+            // For a true junction table, BOTH parents must be required in the URL path:
+            // - Primary scope is always required
+            // - Non-primary scope must have REQUIRES_CONTEXT (not OPTIONAL_CONTEXT)
+            // If the non-primary parent has OPTIONAL_CONTEXT, this is a hierarchical relationship,
+            // not a junction table (e.g., todos with optional todoList parent)
+            const nonPrimaryParent = nonPrimaryScopeParents[0];
+            const isNonPrimaryRequired = nonPrimaryParent.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT;
+            return isNonPrimaryRequired;
+        }
+        return false;
+    }
+    /**
+     * 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)
+     */
+    static generateSyntheticFKParents(resourceConfig, allResourceFieldIdentifiers) {
+        const syntheticParents = [];
+        const resourceIdentifier = resourceConfig.resourceIdentifier;
+        const childRelationships = getChildDirectionRelationships(resourceConfig.resourceRelationships);
+        // Scan child relationships (where current resource is resourceType1/parent)
+        for (const rel of childRelationships) {
+            // Only process relationships with explicit FK field
+            if (!rel.foreignKeyField)
+                continue;
+            // Skip self-referencing relationships
+            if (rel.resourceType2 === resourceIdentifier)
+                continue;
+            // Get standard FK for the parent (current resource = resourceType1)
+            const parentStandardFK = allResourceFieldIdentifiers[rel.resourceType1];
+            if (!parentStandardFK) {
+                // No standard FK defined - skip
+                continue;
+            }
+            // Check if this FK is standard or non-standard
+            // Standard: FK matches the parent's standard field identifier
+            // Non-standard: FK differs (e.g., assignedToUserId instead of userId)
+            const isStandardFK = rel.foreignKeyField === parentStandardFK;
+            if (!isStandardFK) {
+                // Non-standard FK found!
+                // Original relationship: CURRENT → REFERENCED with non-standard FK
+                // Create synthetic: REFERENCED → CURRENT for URL generation
+                // This enables URL pattern: /fk-prefix-referenced/{fkValue}/current
+                const syntheticParent = Resources_SharedUtils.compileRelationshipDeclaration({
+                    // Reverse the relationship for URL nesting
+                    resourceType1: rel.resourceType2, // Referenced resource becomes "parent" for URL
+                    resourceType2: resourceIdentifier, // Current resource becomes "child" for URL
+                    cardinality1: rel.cardinality2,
+                    cardinality2: rel.cardinality1,
+                    // FK reference relationships are never primary scope
+                    isPrimaryScope: false,
+                    primaryScope: undefined,
+                    // Optional parent - generates alternative URL path
+                    parentResourceRequirement: ResourceParentResourceRequirement.OPTIONAL,
+                    // OPTIONAL_CONTEXT ensures URL path is generated
+                    // (STANDALONE would skip, REQUIRES_CONTEXT would make it mandatory)
+                    accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT,
+                    // Basic flags
+                    isDisabled: false,
+                    allowCycle: false,
+                    jointResourceType: undefined,
+                    // Keep foreignKeyField - URL builder uses this for custom prefix
+                    // Example: assignedToUserId → /assigned-to-users/ prefix
+                    foreignKeyField: rel.foreignKeyField,
+                    // DO NOT copy contextPolicy/childOperations - these are for data model.
+                    // Synthetic relationships exist ONLY for URL generation.
+                    contextPolicy: undefined,
+                    nature: RelationshipNature.REFERENCE,
+                    childOperations: undefined,
+                    // discriminator and condition are explicitly set to undefined because
+                    // synthetic FK parents are structural (for URL path generation), not
+                    // data-dependent. They must not carry runtime conditions from the
+                    // original relationship — conditions are evaluated elsewhere (in
+                    // ResourceContext, ServicesRegistryHandler, ContainerNested) when
+                    // processing the real relationship.
+                    discriminator: undefined,
+                    condition: undefined,
+                    display: undefined,
+                });
+                syntheticParents.push(syntheticParent);
+            }
+        }
+        return syntheticParents;
+    }
+}
+//# sourceMappingURL=resources-config-operations.urls-builder.utils.js.map