@craft-ng/core 0.1.1 → 0.1.3

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

@@ -1,12 +1,8 @@
 import * as _angular_core from '@angular/core';
-import { Signal, WritableSignal, ValueEqualityFn, Injector, InjectionToken, Provider, Type, EventEmitter, ResourceRef, ResourceOptions, ResourceStatus, ResourceLoaderParams, ResourceStreamingLoader } from '@angular/core';
+import { WritableSignal, Signal, Injector, InjectionToken, Provider, ValueEqualityFn, Type, EventEmitter, ResourceRef, ResourceOptions, ResourceStatus, ResourceLoaderParams, ResourceStreamingLoader } from '@angular/core';
 import { CompatFieldState, FieldState, ReadonlyArrayLike, MaybeFieldTree, Subfields, FieldTree, SchemaPathTree, PathKind, SchemaPath, SchemaPathRules, ValidationError } from '@angular/forms/signals';
 import { AbstractControl } from '@angular/forms';
 
-type ReadonlySource<T> = Signal<T | undefined> & {
-    preserveLastValue: Signal<T | undefined>;
-} & SourceBranded;
-
 declare const SourceBranded: {
     [SourceBrand]: true;
 };
@@ -24,367 +20,9 @@ declare function createMethodHandlers<State>(methodsData: Record<string, ((...ar
     onStateChange?: (newValue: State) => void;
 }): Record<string, Function>;
 
-type SignalSource<T> = Signal<T | undefined> & {
-    set: (value: T) => void;
+type ReadonlySource<T> = Signal<T | undefined> & {
     preserveLastValue: Signal<T | undefined>;
 } & SourceBranded;
-/**
- * Creates a source for event-driven communication with lazy emission semantics.
- *
- * Sources are the foundation of event-driven patterns in ng-craft, enabling:
- * - Discrete event emissions (unlike continuous signals)
- * - Lazy behavior (undefined until explicitly set)
- * - Decoupled communication between components and stores
- * - Automatic triggering of queries, mutations, and async methods
- * - Multi-listener support with independent subscription timing
- *
- * @remarks
- * **Core Concept:**
- * Sources implement event emitter pattern with reactive semantics:
- * - Emit only when explicitly set (not on every read like signals)
- * - Listeners receive `undefined` on first read (lazy semantics)
- * - New listeners don't receive previous emissions by default
- * - Use `preserveLastValue` to get the last emitted value immediately
- *
- * **Difference from Signals:**
- * - **Signals**: Always have a value, recompute on access, continuous state
- * - **Sources**: Emit on explicit set, lazy by default, discrete events
- * - Sources are for events/actions, signals are for state
- *
- * **Use Cases:**
- * - **User actions**: Button clicks, form submissions, custom events
- * - **Navigation events**: Route changes, tab switches
- * - **Data events**: Reload triggers, refresh requests
- * - **Coordination**: Communication between disconnected components
- * - **Store inputs**: Triggering queries/mutations from components
- * - **Event buses**: Decoupled event communication
- *
- * **Integration with Queries/Mutations:**
- * - Bind to method using `afterRecomputation(source, callback)`
- * - Query/mutation executes automatically when source emits
- * - No manual method exposed (source-based triggering)
- *
- * **Listener Semantics:**
- * - **Standard listener**: Returns `undefined` until source emits, then returns new values only
- * - **preserveLastValue**: Returns last emitted value immediately, then tracks new values
- * - Useful for late subscribers that need current state
- *
- * **Limitations:**
- * Sources are signals and behave differently from observables.
- * Understanding these three key limitations is important:
- * - **Multiple sets in same cycle**: When a source is set multiple times during the same cycle
- *   (between the first set and the Change Detection that executes all consumer callbacks),
- *   consumers will only react once during CD and will only see the last set value.
- *   Intermediate values are discarded.
- * - **Multiple sources order**: Within the same cycle, if multiple sources are triggered,
- *   consumers cannot determine the order in which the sources were set.
- *   The original emission sequence is not preserved.
- * - **Consumer execution order**: When multiple sources are triggered in the same cycle,
- *   consumer callbacks are invoked in the order they were declared, not in the order
- *   their source producers were triggered.
- * - **No synchronous intermediate value reactions**: Unlike observables, sources cannot react
- *   to each intermediate value synchronously. A mechanism similar to observables
- *   (or using native Observable API) without RxJS is being considered to enable
- *   synchronous reactions to intermediate values, matching the behavior currently
- *   offered by observables.
- *
- * @template T - The type of values emitted by the source
- *
- * @param options - Optional configuration:
- *   - `equal`: Custom equality function for change detection (prevents duplicate emissions)
- *   - `debugName`: Name for debugging purposes
- *
- * @returns A source object with:
- *   - `()`: Read current value (undefined until first emission)
- *   - `set(value)`: Emit a value to all listeners
- *   - `preserveLastValue`: Alternative signal that returns last value immediately
- *
- * @example
- * Basic source for user actions
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     loadUser: source<string>(),
- *   }),
- *   craftQuery('user', ({ loadUser }) =>
- *     query({
- *       method: afterRecomputation(loadUser, (userId) => userId),
- *       loader: async ({ params }) => {
- *         const response = await fetch(`/api/users/${params}`);
- *         return response.json();
- *       },
- *     })
- *   )
- * );
- *
- * const store = injectCraft();
- *
- * // Query executes automatically when source emits
- * store.setLoadUser('user-123');
- * // -> loadUser source emits 'user-123'
- * // -> user query executes with params 'user-123'
- *
- * store.setLoadUser('user-456');
- * // -> user query executes again with params 'user-456'
- * ```
- *
- * @example
- * Source for form submission
- * ```ts
- * type FormData = { name: string; email: string };
- *
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     submitForm: source<FormData>(),
- *   }),
- *   craftMutations(({ submitForm }) => ({
- *     submit: mutation({
- *       method: afterRecomputation(submitForm, (data) => data),
- *       loader: async ({ params }) => {
- *         const response = await fetch('/api/submit', {
- *           method: 'POST',
- *           body: JSON.stringify(params),
- *         });
- *         return response.json();
- *       },
- *     }),
- *   }))
- * );
- *
- * const store = injectCraft();
- *
- * // In component template:
- * // <form (submit)="onSubmit()">
- * //   <input name="name" [(ngModel)]="formData.name" />
- * //   <input name="email" [(ngModel)]="formData.email" />
- * // </form>
- *
- * onSubmit() {
- *   // Mutation executes automatically
- *   this.store.setSubmitForm(this.formData);
- *   // -> submitForm source emits
- *   // -> submit mutation executes
- * }
- * ```
- *
- * @example
- * Source for reload/refresh actions
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     reload: source<void>(),
- *   }),
- *   craftQuery('data', ({ reload }) =>
- *     query(
- *       {
- *         params: () => ({}),
- *         loader: async () => {
- *           const response = await fetch('/api/data');
- *           return response.json();
- *         },
- *       },
- *       insertReloadOnSource(reload)
- *     )
- *   )
- * );
- *
- * const store = injectCraft();
- *
- * // Trigger reload from anywhere
- * store.setReload();
- * // -> reload source emits
- * // -> query reloads
- *
- * // In component:
- * // <button (click)="store.setReload()">Refresh</button>
- * ```
- *
- * @example
- * Multiple sources for different actions
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     addTodo: source<{ text: string }>(),
- *     deleteTodo: source<string>(),
- *     toggleTodo: source<string>(),
- *   }),
- *   craftMutations(({ addTodo, deleteTodo, toggleTodo }) => ({
- *     create: mutation({
- *       method: afterRecomputation(addTodo, (data) => data),
- *       loader: async ({ params }) => {
- *         const response = await fetch('/api/todos', {
- *           method: 'POST',
- *           body: JSON.stringify(params),
- *         });
- *         return response.json();
- *       },
- *     }),
- *     delete: mutation({
- *       method: afterRecomputation(deleteTodo, (id) => id),
- *       loader: async ({ params }) => {
- *         await fetch(`/api/todos/${params}`, { method: 'DELETE' });
- *         return { deleted: true };
- *       },
- *     }),
- *     toggle: mutation({
- *       method: afterRecomputation(toggleTodo, (id) => id),
- *       loader: async ({ params }) => {
- *         const response = await fetch(`/api/todos/${params}/toggle`, {
- *           method: 'PATCH',
- *         });
- *         return response.json();
- *       },
- *     }),
- *   }))
- * );
- *
- * const store = injectCraft();
- *
- * // Different actions trigger different mutations
- * store.setAddTodo({ text: 'Buy milk' });
- * store.setToggleTodo('todo-123');
- * store.setDeleteTodo('todo-456');
- * ```
- *
- * @example
- * Late listener with preserveLastValue
- * ```ts
- * const mySource = source<string>();
- *
- * // Early listener
- * const listener1 = computed(() => mySource());
- * console.log(listener1()); // undefined
- *
- * // Emit value
- * mySource.set('Hello');
- * console.log(listener1()); // 'Hello'
- *
- * // Late listener (after emission)
- * const listener2 = computed(() => mySource());
- * console.log(listener2()); // undefined (doesn't get previous emission)
- *
- * mySource.set('World');
- * console.log(listener1()); // 'World'
- * console.log(listener2()); // 'World'
- *
- * // Using preserveLastValue for late listeners
- * const listener3 = computed(() => mySource.preserveLastValue());
- * console.log(listener3()); // 'World' (gets last value immediately)
- * ```
- *
- * @example
- * Custom equality to prevent duplicate emissions
- * ```ts
- * type Params = { id: string; timestamp: number };
- *
- * const paramsSource = source<Params>({
- *   equal: (a, b) => a?.id === b?.id, // Compare only by id
- * });
- *
- * const listener = computed(() => paramsSource());
- *
- * paramsSource.set({ id: 'item-1', timestamp: Date.now() });
- * // -> listener receives value
- *
- * paramsSource.set({ id: 'item-1', timestamp: Date.now() });
- * // -> listener does NOT receive value (same id)
- *
- * paramsSource.set({ id: 'item-2', timestamp: Date.now() });
- * // -> listener receives value (different id)
- * ```
- *
- * @example
- * Source for coordinating multiple components
- * ```ts
- * // Global source (outside component)
- * const refreshAllSource = source<void>();
- *
- * // Component A
- * @Component({
- *   selector: 'app-data-view',
- *   template: '...',
- * })
- * export class DataViewComponent {
- *   { injectCraft } = craft(
- *     { name: '', providedIn: 'root' },
- *     craftQuery('data', () =>
- *       query(
- *         {
- *           params: () => ({}),
- *           loader: async () => {
- *             const response = await fetch('/api/data');
- *             return response.json();
- *           },
- *         },
- *         insertReloadOnSource(refreshAllSource)
- *       )
- *     )
- *   );
- *
- *   store = this.injectCraft();
- * }
- *
- * // Component B
- * @Component({
- *   selector: 'app-refresh-button',
- *   template: '<button (click)="refresh()">Refresh All</button>',
- * })
- * export class RefreshButtonComponent {
- *   refresh() {
- *     // Triggers refresh in all components listening to this source
- *     refreshAllSource.set();
- *   }
- * }
- * ```
- *
- * @example
- * Source with complex payload
- * ```ts
- * type SearchParams = {
- *   query: string;
- *   filters: string[];
- *   page: number;
- * };
- *
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     search: source<SearchParams>(),
- *   }),
- *   craftQuery('results', ({ search }) =>
- *     query({
- *       method: afterRecomputation(search, (params) => params),
- *       loader: async ({ params }) => {
- *         const queryString = new URLSearchParams({
- *           q: params.query,
- *           filters: params.filters.join(','),
- *           page: String(params.page),
- *         });
- *         const response = await fetch(`/api/search?${queryString}`);
- *         return response.json();
- *       },
- *     })
- *   )
- * );
- *
- * const store = injectCraft();
- *
- * // Emit complex search parameters
- * store.setSearch({
- *   query: 'angular',
- *   filters: ['tutorial', 'advanced'],
- *   page: 1,
- * });
- * ```
- */
-declare function signalSource<T>(options?: {
-    equal?: ValueEqualityFn<NoInfer<T> | undefined>;
-    debugName?: string;
-}): SignalSource<T>;
 
 /**
  * Creates a derived readonly source that transforms source emissions through a callback function.
@@ -691,7 +329,7 @@ declare function signalSource<T>(options?: {
  * // -> mutation receives exact same object
  * ```
  */
-declare function afterRecomputation<State, SourceType>(_source: SignalSource<SourceType>, callback: (source: SourceType) => State): ReadonlySource<State>;
+declare function afterRecomputation<State, SourceType>(_source: ReadonlySource<SourceType>, callback: (source: SourceType) => State): ReadonlySource<State>;
 
 type ContextConstraints = {
     props: {};
@@ -2167,6 +1805,368 @@ declare function craft<outputs1 extends ContextConstraints, standaloneOutputs1 e
     implements?: ToImplementContract;
 }>;
 
+type SignalSource<T> = Signal<T | undefined> & {
+    set: (value: T) => void;
+    preserveLastValue: Signal<T | undefined>;
+} & SourceBranded;
+/**
+ * Creates a source for event-driven communication with lazy emission semantics.
+ *
+ * Sources are the foundation of event-driven patterns in ng-craft, enabling:
+ * - Discrete event emissions (unlike continuous signals)
+ * - Lazy behavior (undefined until explicitly set)
+ * - Decoupled communication between components and stores
+ * - Automatic triggering of queries, mutations, and async methods
+ * - Multi-listener support with independent subscription timing
+ *
+ * @remarks
+ * **Core Concept:**
+ * Sources implement event emitter pattern with reactive semantics:
+ * - Emit only when explicitly set (not on every read like signals)
+ * - Listeners receive `undefined` on first read (lazy semantics)
+ * - New listeners don't receive previous emissions by default
+ * - Use `preserveLastValue` to get the last emitted value immediately
+ *
+ * **Difference from Signals:**
+ * - **Signals**: Always have a value, recompute on access, continuous state
+ * - **Sources**: Emit on explicit set, lazy by default, discrete events
+ * - Sources are for events/actions, signals are for state
+ *
+ * **Use Cases:**
+ * - **User actions**: Button clicks, form submissions, custom events
+ * - **Navigation events**: Route changes, tab switches
+ * - **Data events**: Reload triggers, refresh requests
+ * - **Coordination**: Communication between disconnected components
+ * - **Store inputs**: Triggering queries/mutations from components
+ * - **Event buses**: Decoupled event communication
+ *
+ * **Integration with Queries/Mutations:**
+ * - Bind to method using `afterRecomputation(source, callback)`
+ * - Query/mutation executes automatically when source emits
+ * - No manual method exposed (source-based triggering)
+ *
+ * **Listener Semantics:**
+ * - **Standard listener**: Returns `undefined` until source emits, then returns new values only
+ * - **preserveLastValue**: Returns last emitted value immediately, then tracks new values
+ * - Useful for late subscribers that need current state
+ *
+ * **Limitations:**
+ * Sources are signals and behave differently from observables.
+ * Understanding these three key limitations is important:
+ * - **Multiple sets in same cycle**: When a source is set multiple times during the same cycle
+ *   (between the first set and the Change Detection that executes all consumer callbacks),
+ *   consumers will only react once during CD and will only see the last set value.
+ *   Intermediate values are discarded.
+ * - **Multiple sources order**: Within the same cycle, if multiple sources are triggered,
+ *   consumers cannot determine the order in which the sources were set.
+ *   The original emission sequence is not preserved.
+ * - **Consumer execution order**: When multiple sources are triggered in the same cycle,
+ *   consumer callbacks are invoked in the order they were declared, not in the order
+ *   their source producers were triggered.
+ * - **No synchronous intermediate value reactions**: Unlike observables, sources cannot react
+ *   to each intermediate value synchronously. A mechanism similar to observables
+ *   (or using native Observable API) without RxJS is being considered to enable
+ *   synchronous reactions to intermediate values, matching the behavior currently
+ *   offered by observables.
+ *
+ * @template T - The type of values emitted by the source
+ *
+ * @param options - Optional configuration:
+ *   - `equal`: Custom equality function for change detection (prevents duplicate emissions)
+ *   - `debugName`: Name for debugging purposes
+ *
+ * @returns A source object with:
+ *   - `()`: Read current value (undefined until first emission)
+ *   - `set(value)`: Emit a value to all listeners
+ *   - `preserveLastValue`: Alternative signal that returns last value immediately
+ *
+ * @example
+ * Basic source for user actions
+ * ```ts
+ * const { injectCraft } = craft(
+ *   { name: '', providedIn: 'root' },
+ *   craftSources({
+ *     loadUser: source<string>(),
+ *   }),
+ *   craftQuery('user', ({ loadUser }) =>
+ *     query({
+ *       method: afterRecomputation(loadUser, (userId) => userId),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch(`/api/users/${params}`);
+ *         return response.json();
+ *       },
+ *     })
+ *   )
+ * );
+ *
+ * const store = injectCraft();
+ *
+ * // Query executes automatically when source emits
+ * store.setLoadUser('user-123');
+ * // -> loadUser source emits 'user-123'
+ * // -> user query executes with params 'user-123'
+ *
+ * store.setLoadUser('user-456');
+ * // -> user query executes again with params 'user-456'
+ * ```
+ *
+ * @example
+ * Source for form submission
+ * ```ts
+ * type FormData = { name: string; email: string };
+ *
+ * const { injectCraft } = craft(
+ *   { name: '', providedIn: 'root' },
+ *   craftSources({
+ *     submitForm: source<FormData>(),
+ *   }),
+ *   craftMutations(({ submitForm }) => ({
+ *     submit: mutation({
+ *       method: afterRecomputation(submitForm, (data) => data),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch('/api/submit', {
+ *           method: 'POST',
+ *           body: JSON.stringify(params),
+ *         });
+ *         return response.json();
+ *       },
+ *     }),
+ *   }))
+ * );
+ *
+ * const store = injectCraft();
+ *
+ * // In component template:
+ * // <form (submit)="onSubmit()">
+ * //   <input name="name" [(ngModel)]="formData.name" />
+ * //   <input name="email" [(ngModel)]="formData.email" />
+ * // </form>
+ *
+ * onSubmit() {
+ *   // Mutation executes automatically
+ *   this.store.setSubmitForm(this.formData);
+ *   // -> submitForm source emits
+ *   // -> submit mutation executes
+ * }
+ * ```
+ *
+ * @example
+ * Source for reload/refresh actions
+ * ```ts
+ * const { injectCraft } = craft(
+ *   { name: '', providedIn: 'root' },
+ *   craftSources({
+ *     reload: source<void>(),
+ *   }),
+ *   craftQuery('data', ({ reload }) =>
+ *     query(
+ *       {
+ *         params: () => ({}),
+ *         loader: async () => {
+ *           const response = await fetch('/api/data');
+ *           return response.json();
+ *         },
+ *       },
+ *       insertReloadOnSource(reload)
+ *     )
+ *   )
+ * );
+ *
+ * const store = injectCraft();
+ *
+ * // Trigger reload from anywhere
+ * store.setReload();
+ * // -> reload source emits
+ * // -> query reloads
+ *
+ * // In component:
+ * // <button (click)="store.setReload()">Refresh</button>
+ * ```
+ *
+ * @example
+ * Multiple sources for different actions
+ * ```ts
+ * const { injectCraft } = craft(
+ *   { name: '', providedIn: 'root' },
+ *   craftSources({
+ *     addTodo: source<{ text: string }>(),
+ *     deleteTodo: source<string>(),
+ *     toggleTodo: source<string>(),
+ *   }),
+ *   craftMutations(({ addTodo, deleteTodo, toggleTodo }) => ({
+ *     create: mutation({
+ *       method: afterRecomputation(addTodo, (data) => data),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch('/api/todos', {
+ *           method: 'POST',
+ *           body: JSON.stringify(params),
+ *         });
+ *         return response.json();
+ *       },
+ *     }),
+ *     delete: mutation({
+ *       method: afterRecomputation(deleteTodo, (id) => id),
+ *       loader: async ({ params }) => {
+ *         await fetch(`/api/todos/${params}`, { method: 'DELETE' });
+ *         return { deleted: true };
+ *       },
+ *     }),
+ *     toggle: mutation({
+ *       method: afterRecomputation(toggleTodo, (id) => id),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch(`/api/todos/${params}/toggle`, {
+ *           method: 'PATCH',
+ *         });
+ *         return response.json();
+ *       },
+ *     }),
+ *   }))
+ * );
+ *
+ * const store = injectCraft();
+ *
+ * // Different actions trigger different mutations
+ * store.setAddTodo({ text: 'Buy milk' });
+ * store.setToggleTodo('todo-123');
+ * store.setDeleteTodo('todo-456');
+ * ```
+ *
+ * @example
+ * Late listener with preserveLastValue
+ * ```ts
+ * const mySource = source<string>();
+ *
+ * // Early listener
+ * const listener1 = computed(() => mySource());
+ * console.log(listener1()); // undefined
+ *
+ * // Emit value
+ * mySource.set('Hello');
+ * console.log(listener1()); // 'Hello'
+ *
+ * // Late listener (after emission)
+ * const listener2 = computed(() => mySource());
+ * console.log(listener2()); // undefined (doesn't get previous emission)
+ *
+ * mySource.set('World');
+ * console.log(listener1()); // 'World'
+ * console.log(listener2()); // 'World'
+ *
+ * // Using preserveLastValue for late listeners
+ * const listener3 = computed(() => mySource.preserveLastValue());
+ * console.log(listener3()); // 'World' (gets last value immediately)
+ * ```
+ *
+ * @example
+ * Custom equality to prevent duplicate emissions
+ * ```ts
+ * type Params = { id: string; timestamp: number };
+ *
+ * const paramsSource = source<Params>({
+ *   equal: (a, b) => a?.id === b?.id, // Compare only by id
+ * });
+ *
+ * const listener = computed(() => paramsSource());
+ *
+ * paramsSource.set({ id: 'item-1', timestamp: Date.now() });
+ * // -> listener receives value
+ *
+ * paramsSource.set({ id: 'item-1', timestamp: Date.now() });
+ * // -> listener does NOT receive value (same id)
+ *
+ * paramsSource.set({ id: 'item-2', timestamp: Date.now() });
+ * // -> listener receives value (different id)
+ * ```
+ *
+ * @example
+ * Source for coordinating multiple components
+ * ```ts
+ * // Global source (outside component)
+ * const refreshAllSource = source<void>();
+ *
+ * // Component A
+ * @Component({
+ *   selector: 'app-data-view',
+ *   template: '...',
+ * })
+ * export class DataViewComponent {
+ *   { injectCraft } = craft(
+ *     { name: '', providedIn: 'root' },
+ *     craftQuery('data', () =>
+ *       query(
+ *         {
+ *           params: () => ({}),
+ *           loader: async () => {
+ *             const response = await fetch('/api/data');
+ *             return response.json();
+ *           },
+ *         },
+ *         insertReloadOnSource(refreshAllSource)
+ *       )
+ *     )
+ *   );
+ *
+ *   store = this.injectCraft();
+ * }
+ *
+ * // Component B
+ * @Component({
+ *   selector: 'app-refresh-button',
+ *   template: '<button (click)="refresh()">Refresh All</button>',
+ * })
+ * export class RefreshButtonComponent {
+ *   refresh() {
+ *     // Triggers refresh in all components listening to this source
+ *     refreshAllSource.set();
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Source with complex payload
+ * ```ts
+ * type SearchParams = {
+ *   query: string;
+ *   filters: string[];
+ *   page: number;
+ * };
+ *
+ * const { injectCraft } = craft(
+ *   { name: '', providedIn: 'root' },
+ *   craftSources({
+ *     search: source<SearchParams>(),
+ *   }),
+ *   craftQuery('results', ({ search }) =>
+ *     query({
+ *       method: afterRecomputation(search, (params) => params),
+ *       loader: async ({ params }) => {
+ *         const queryString = new URLSearchParams({
+ *           q: params.query,
+ *           filters: params.filters.join(','),
+ *           page: String(params.page),
+ *         });
+ *         const response = await fetch(`/api/search?${queryString}`);
+ *         return response.json();
+ *       },
+ *     })
+ *   )
+ * );
+ *
+ * const store = injectCraft();
+ *
+ * // Emit complex search parameters
+ * store.setSearch({
+ *   query: 'angular',
+ *   filters: ['tutorial', 'advanced'],
+ *   page: 1,
+ * });
+ * ```
+ */
+declare function signalSource<T>(options?: {
+    equal?: ValueEqualityFn<NoInfer<T> | undefined>;
+    debugName?: string;
+}): SignalSource<T>;
+
 type ExtractSignalPropsAndMethods<State, StateKeysTuple, Acc extends {
     props: {};
     methods: Record<string, Function>;
@@ -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 };