@craft-ng/core 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-ng/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Reactive State Management for Angular - Type-safe, signal-based utilities for composable and reusable state management",
   "author": "Romain Geffrault",
   "license": "MIT",

package/types/craft-ng-core.d.ts

@@ -9265,5 +9265,130 @@ declare function insertFormSubmit<FormValue, MutationValue, MutationParams, Muta
     submitExceptions: Signal<ToSubmitExceptions<InsertMetaInCraftExceptionIfExists<MutationExceptions['params'], 'params', MutationIdentifier> | InsertMetaInCraftExceptionIfExists<MutationExceptions['loader'], 'loader', MutationIdentifier>, SuccessExceptions, ErrorExceptions, ExceptionExceptions, FormIdentifier>[]>;
 }>;
 
-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 };
+type ArrayObjectDeepPath<State extends object> = ObjectDeepPath<State> extends infer Path ? Path extends string ? AccessTypeObjectPropertyByDottedPath<State, DottedPathPathToTuple<Path>> extends Array<any> ? Path : never : never : never;
+type DottedPathToCamel<Path extends string> = Path extends `${infer Head}.${infer Tail}` ? `${Head}${Capitalize<DottedPathToCamel<Tail>>}` : Path;
+type EntitiesUtilsToMap<EntityHelperFns, Entity, K, HasStateIdentifier, StateIdentifier, HasPath, Path, Acc = {}> = EntityHelperFns extends [infer First, ...infer Rest] ? First extends (data: infer Payload) => infer R ? R extends EntitiesUtilBrand<infer Name> ? EntitiesUtilsToMap<Rest, Entity, K, HasStateIdentifier, StateIdentifier, HasPath, Path, Acc & {
+    [key in Name as `${HasPath extends true ? `${DottedPathToCamel<Path & string>}${Capitalize<string & key>}` : key & string}`]: (payload: MergeObject$1<{
+        [key in Exclude<keyof Payload, 'identifier'> as `${key extends 'entities' ? never : key & string}`]: key extends 'entity' ? Entity : key extends 'ids' ? K[] : key extends 'newEntities' ? Entity[] : `Not implemented mapping for ${key & string}`;
+    }, HasStateIdentifier extends true ? {
+        select: StateIdentifier extends (...args: any) => infer R ? R : never;
+    } : {}>) => void;
+}> : 'No EntitiesBranded Name Detected' : false : Acc;
+/**
+ * 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}
+ */
+declare function insertEntities<State, K extends string | number, PreviousInsertionsOutputs, const EntityHelperFns extends unknown[], StateIdentifier, const Path = State extends Array<infer Entity> ? never : State extends object ? ArrayObjectDeepPath<State> : never, StateType = State extends Array<infer R> ? R : State extends object ? Path extends string ? AccessTypeObjectPropertyByDottedPath<State, DottedPathPathToTuple<Path>> extends Array<infer Entity> ? Entity : never : never : never, HasStateIdentifier = [unknown] extends [StateIdentifier] ? false : StateIdentifier extends (...args: any) => infer R ? [unknown] extends [R] ? false : true : false, IsEntityIdentifierOptional = StateType extends {
+    id: NoInfer<K>;
+} ? true : StateType extends string | number ? true : false>(config: {
+    methods: EntityHelperFns;
+} & MergeObject$1<IsEntityIdentifierOptional extends true ? {
+    identifier?: IdSelector<NoInfer<StateType>, NoInfer<K>>;
+} : {
+    identifier: IdSelector<NoInfer<StateType>, NoInfer<K>>;
+}, [
+    Path
+] extends [never] ? {} : {
+    path: Path;
+}>): (context: InsertionStateFactoryContext<State, PreviousInsertionsOutputs> & {
+    identifier?: StateIdentifier;
+}) => Prettify<EntitiesUtilsToMap<EntityHelperFns, StateType, K, HasStateIdentifier, StateIdentifier, "path" extends keyof typeof config ? true : false, Path>> & {
+    testState: State;
+    testPath: Path;
+    testHasPath: "path" extends keyof typeof config ? true : false;
+};
+
+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 };
 export type { AnyCraftException, AsyncProcessExceptionConstraints, AsyncProcessOutput, AsyncProcessRef, CEmailException, CMaxException, CMaxLengthException, CMinException, CMinLengthException, CRequiredException, CloudProxy, CloudProxySource, ContextConstraints, ContextInput, CraftException, CraftExceptionMeta, CraftExceptionResult, CraftFactory, CraftFactoryEntries, CraftFactoryUtility, DeferredExtract, EntitiesUtilBrand, EqualParams, ExcludeByCode, ExcludeCommonKeys, ExposedStateInsertions, ExtractCodeFromCraftResultUnion, ExtractCraftException, ExtractSignalPropsAndMethods, FilterMethodsBoundToSources, FilterPrivateFields, FilterSource, FlatRecord, FormNodeExceptions, FormWithInsertions, FromEventToSource$, HasChild$1 as HasChild, HasKeys, IdSelector, Identifier, InferInjectedType, InjectService2InsertionContext, InjectService2InsertionFactory, InjectService2Insertions, InjectService2Output, InjectService2Public, InsertFormAttributesConfig, InsertFormAttributesContext, InsertMetaInCraftExceptionIfExists, InsertionFormFactoryContext, InsertionsFormFactory, IsAny, IsEmptyObject, IsNever, IsUnknown, MakeOptionalPropertiesRequired$1 as MakeOptionalPropertiesRequired, MergeObject$1 as MergeObject, MergeObjects$1 as MergeObjects, MergeTwoContexts, MutationOutput, MutationRef, Not, OmitStrict, PartialContext, Prettify, QueryOutput, QueryParamConfig, QueryParamExceptions, QueryParamNavigationOptions$1 as QueryParamNavigationOptions, QueryParamOutput, QueryParamsToState, QueryRef, ReadonlySource, ReadonlySource$, RemoveIndexSignature, ReplaceStoreConfigToken, ResourceByIdHandler, ResourceByIdLikeAsyncProcessExceptions, ResourceByIdLikeExceptions, ResourceByIdLikeMutationExceptions, ResourceByIdLikeMutationRef, ResourceByIdLikeQueryRef, ResourceByIdRef, ResourceLikeAsyncProcessExceptions, ResourceLikeExceptions, ResourceLikeMutationExceptions, ResourceLikeMutationRef, ResourceLikeQueryRef, SignalSource, Source$, SourceFromEvent, SourceSetterMethods, SourceSubscribe, SpecificCraftQueryParamOutputs, SpecificCraftQueryParamsOutputs, StackSource, StateOutput, StoreConfigConstraints, StoreConfigToken, StripCraftException, ToConnectableMethodFromInject, ToConnectableSourceFromInject, ToInjectBindings, UnionToIntersection$1 as UnionToIntersection, UnionToTuple$1 as UnionToTuple, Update, ValidatedFormValue, ValidatorBindingContext, ValidatorModel, ValidatorOutput, ValidatorPending, ValidatorSuccess, ValidatorType, ValidatorUtilBrand };