@craft-ng/core 0.1.1 → 0.1.3

package/fesm2022/craft-ng-core.mjs

@@ -10387,9 +10387,167 @@ function insertFormSubmit(submitCraftResource, config) {
     };
 }
 
+/**
+ * Creates an insertion that adds entity collection management methods to state, query, or queryParam primitives.
+ *
+ * Provides type-safe manipulation of arrays of entities with operations like add, remove, update, and upsert.
+ * Supports nested properties via dot notation paths and custom entity identifiers.
+ *
+ * @template State - The state type (array or object containing arrays)
+ * @template K - The type of entity identifiers (string or number)
+ * @template PreviousInsertionsOutputs - Combined outputs from previous insertions
+ * @template EntityHelperFns - Tuple type of entity utility functions to expose
+ * @template StateIdentifier - Type of identifier function for parallel queries
+ * @template Path - Dot-notation path to nested array (inferred from state structure)
+ *
+ * @param config - Configuration object
+ * @param config.methods - Array of entity utility functions (addOne, removeOne, updateOne, etc.) to expose as methods
+ * @param config.identifier - Optional custom function to extract unique ID from entities.
+ *                            Defaults to `entity.id` for objects or `entity` for primitives
+ * @param config.path - Optional dot-notation path to nested array property (e.g., 'catalog.products').
+ *                      Method names are prefixed with camelCase path when provided
+ *
+ * @returns Insertion function that adds entity management methods to the primitive
+ *
+ * @example
+ * // Basic usage with primitives
+ * const tags = state(
+ *   [] as string[],
+ *   insertEntities({
+ *     methods: [addOne, addMany, removeOne],
+ *   })
+ * );
+ * tags.addOne({ entity: 'typescript' });
+ * tags.addMany({ newEntities: ['angular', 'signals'] });
+ *
+ * @example
+ * // With objects having default id property
+ * interface Product {
+ *   id: string;
+ *   name: string;
+ *   price: number;
+ * }
+ * const products = state(
+ *   [] as Product[],
+ *   insertEntities({
+ *     methods: [addOne, setOne, removeOne],
+ *   })
+ * );
+ * products.addOne({ entity: { id: '1', name: 'Laptop', price: 999 } });
+ *
+ * @example
+ * // With custom identifier
+ * interface User {
+ *   uuid: string;
+ *   name: string;
+ * }
+ * const users = state(
+ *   [] as User[],
+ *   insertEntities({
+ *     methods: [setOne, removeOne],
+ *     identifier: (user) => user.uuid,
+ *   })
+ * );
+ *
+ * @example
+ * // With nested path
+ * interface Catalog {
+ *   total: number;
+ *   products: Array<{ id: string; name: string }>;
+ * }
+ * const catalog = state(
+ *   { total: 0, products: [] } as Catalog,
+ *   insertEntities({
+ *     methods: [addMany, removeOne],
+ *     path: 'products',
+ *   })
+ * );
+ * catalog.productsAddMany({ newEntities: [{ id: '1', name: 'Item' }] });
+ *
+ * @example
+ * // With parallel queries
+ * const userQuery = query(
+ *   {
+ *     params: () => 'userId',
+ *     identifier: (params) => params,
+ *     loader: async ({ params }) => fetchUserPosts(params),
+ *   },
+ *   insertEntities({
+ *     methods: [addOne],
+ *   })
+ * );
+ * userQuery.addOne({
+ *   select: 'user-123', // Target specific query instance
+ *   entity: { id: 'post-1', title: 'New Post' },
+ * });
+ *
+ * @see {@link https://github.com/ng-angular-stack/ng-craft/blob/main/apps/docs/insertions/insert-entities.md | insertEntities Documentation}
+ */
+function insertEntities(config) {
+    return (context) => {
+        const methods = {};
+        const hasPath = 'path' in config;
+        const path = hasPath ? config.path : undefined;
+        const pathKeys = path ? path.split('.') : undefined;
+        const pathMethodPrefix = pathKeys
+            ? pathKeys.reduce((acc, key, index) => index === 0 ? key : `${acc}${key[0].toUpperCase()}${key.slice(1)}`, '')
+            : undefined;
+        for (const helperFn of config.methods) {
+            const helperName = helperFn.name;
+            if (!helperName) {
+                continue;
+            }
+            const methodName = hasPath
+                ? `${pathMethodPrefix}${helperName[0].toUpperCase()}${helperName.slice(1)}`
+                : helperName;
+            methods[methodName] = (payload) => {
+                context.update((state) => {
+                    const hasSelect = 'select' in payload && payload.select;
+                    const targetState = hasSelect
+                        ? state[payload.select]
+                        : state;
+                    const entities = pathKeys
+                        ? getNestedStateValue({
+                            state: targetState,
+                            keysPath: pathKeys,
+                        })
+                        : targetState;
+                    const updatedEntities = helperFn({
+                        ...payload,
+                        entities,
+                        identifier: config.identifier,
+                    });
+                    if (hasSelect) {
+                        const updatedTargetState = pathKeys
+                            ? createNestedStateUpdate({
+                                state: targetState,
+                                keysPath: pathKeys,
+                                value: updatedEntities,
+                            })
+                            : updatedEntities;
+                        return {
+                            ...state,
+                            [payload.select]: updatedTargetState,
+                        };
+                    }
+                    if (pathKeys) {
+                        return createNestedStateUpdate({
+                            state,
+                            keysPath: pathKeys,
+                            value: updatedEntities,
+                        });
+                    }
+                    return updatedEntities;
+                });
+            };
+        }
+        return methods;
+    };
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { CRAFT_EXCEPTION_SYMBOL, EXTERNALLY_PROVIDED, EmptyContext, GlobalPersisterHandlerService, STORE_CONFIG_TOKEN, SourceBrand, SourceBranded, VALIDATOR_OUTPUT_SYMBOL, addMany, addOne, afterRecomputation, asyncProcess, cAsyncValidate, cAsyncValidator, cEmail, cMax, cMaxLength, cMin, cMinLength, cPattern, cRequired, cValidate, cValidator, capitalize, computedIds, computedSource, computedTotal, contract, craft, craftAsyncProcesses, craftComputedStates, craftException, craftFactoryEntries, craftInject, craftInputs, craftMutations, craftQuery, craftQueryParam, craftQueryParams, craftSetAllQueriesParamsStandalone, craftSources, craftState, createMethodHandlers, fromEventToSource$, injectService, insertForm, insertFormAttributes, insertFormSubmit, insertLocalStoragePersister, insertNoopTypingAnchor, insertPaginationPlaceholderData, insertReactOnMutation, insertSelect, insertSelectFormTree, isCraftException, isSource, linkedSource, localStoragePersister, map, mapOne, mutation, on$, partialContext, query, queryParam, reactiveWritableSignal, removeAll, removeMany, removeOne, resourceById, serializeQueryParams, serializedQueryParamsObjectToString, setAll, setMany, setOne, signalSource, source$, sourceFromEvent, stackedSource, state, toInject, toSource, toggleMany, toggleOne, updateMany, updateOne, upsertMany, upsertOne, validatedFormValueSymbol };
+export { CRAFT_EXCEPTION_SYMBOL, EXTERNALLY_PROVIDED, EmptyContext, GlobalPersisterHandlerService, STORE_CONFIG_TOKEN, SourceBrand, SourceBranded, VALIDATOR_OUTPUT_SYMBOL, addMany, addOne, afterRecomputation, asyncProcess, cAsyncValidate, cAsyncValidator, cEmail, cMax, cMaxLength, cMin, cMinLength, cPattern, cRequired, cValidate, cValidator, capitalize, computedIds, computedSource, computedTotal, contract, craft, craftAsyncProcesses, craftComputedStates, craftException, craftFactoryEntries, craftInject, craftInputs, craftMutations, craftQuery, craftQueryParam, craftQueryParams, craftSetAllQueriesParamsStandalone, craftSources, craftState, createMethodHandlers, fromEventToSource$, injectService, insertEntities, insertForm, insertFormAttributes, insertFormSubmit, insertLocalStoragePersister, insertNoopTypingAnchor, insertPaginationPlaceholderData, insertReactOnMutation, insertSelect, insertSelectFormTree, isCraftException, isSource, linkedSource, localStoragePersister, map, mapOne, mutation, on$, partialContext, query, queryParam, reactiveWritableSignal, removeAll, removeMany, removeOne, resourceById, serializeQueryParams, serializedQueryParamsObjectToString, setAll, setMany, setOne, signalSource, source$, sourceFromEvent, stackedSource, state, toInject, toSource, toggleMany, toggleOne, updateMany, updateOne, upsertMany, upsertOne, validatedFormValueSymbol };
 //# sourceMappingURL=craft-ng-core.mjs.map