@craft-ng/core 0.1.0 → 0.1.2

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,92 +20,67 @@ 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.
+ * Creates a derived readonly source that transforms source emissions through a callback function.
  *
- * 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
+ * This function binds queries, mutations, and async methods to sources for automatic execution by:
+ * - Listening to source emissions and computing new values
+ * - Providing a readonly source suitable for method binding
+ * - Maintaining reactivity through Angular's effect system
+ * - Enabling source-based triggering patterns
  *
  * @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
+ * **Primary Use Case:**
+ * Bind queries/mutations/async methods to sources for automatic execution:
+ * ```ts
+ * method: afterRecomputation(mySource, (data) => data)
+ * ```
+ * This pattern makes queries/mutations execute automatically when the source emits.
  *
- * **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
+ * **Execution Flow:**
+ * 1. Source emits a value via `source.set(value)`
+ * 2. afterRecomputation callback transforms the value
+ * 3. Resulting readonly source emits the transformed value
+ * 4. Bound query/mutation/async method executes with the new value
  *
- * **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)
+ * **Difference from computedSource:**
+ * - `afterRecomputation`: Designed for binding to method parameters
+ * - `computedSource`: General-purpose source transformation
+ * - Both transform source values, but afterRecomputation is optimized for method binding
  *
- * **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
+ * **Common Patterns:**
+ * - **Identity transformation**: `afterRecomputation(source, (x) => x)` - pass value through
+ * - **Field extraction**: `afterRecomputation(source, (data) => data.id)` - extract specific field
+ * - **Validation**: `afterRecomputation(source, (data) => validate(data))` - transform and validate
+ * - **Mapping**: `afterRecomputation(source, (data) => mapToDto(data))` - convert to different type
  *
- * **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 State - The type of values produced by the callback
+ * @template SourceType - The type of values emitted by the origin source
  *
- * @template T - The type of values emitted by the source
+ * @param _source - The source to listen to.
+ *   When this source emits, the callback is invoked.
  *
- * @param options - Optional configuration:
- *   - `equal`: Custom equality function for change detection (prevents duplicate emissions)
- *   - `debugName`: Name for debugging purposes
+ * @param callback - Function that transforms source values.
+ *   Receives the emitted value and returns the transformed result.
  *
- * @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
+ * @returns A readonly source that emits transformed values.
+ *   Can be used as the `method` parameter in queries, mutations, and async methods.
  *
  * @example
- * Basic source for user actions
+ * Binding a query to a source for automatic execution
  * ```ts
  * const { injectCraft } = craft(
  *   { name: '', providedIn: 'root' },
  *   craftSources({
- *     loadUser: source<string>(),
+ *     userIdChange: source<string>(),
  *   }),
- *   craftQuery('user', ({ loadUser }) =>
+ *   craftQuery('user', ({ userIdChange }) =>
  *     query({
- *       method: afterRecomputation(loadUser, (userId) => userId),
+ *       method: afterRecomputation(userIdChange, (userId) => userId),
  *       loader: async ({ params }) => {
  *         const response = await fetch(`/api/users/${params}`);
  *         return response.json();
@@ -121,27 +92,24 @@ type SignalSource<T> = Signal<T | undefined> & {
  * 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.setUserIdChange('user-123');
+ * // -> query loader executes with params 'user-123'
  *
- * store.setLoadUser('user-456');
- * // -> user query executes again with params 'user-456'
+ * store.setUserIdChange('user-456');
+ * // -> query loader executes again with params 'user-456'
  * ```
  *
  * @example
- * Source for form submission
+ * Binding a mutation to a source
  * ```ts
- * type FormData = { name: string; email: string };
- *
  * const { injectCraft } = craft(
  *   { name: '', providedIn: 'root' },
  *   craftSources({
- *     submitForm: source<FormData>(),
+ *     submitForm: source<{ name: string; email: string }>(),
  *   }),
  *   craftMutations(({ submitForm }) => ({
  *     submit: mutation({
- *       method: afterRecomputation(submitForm, (data) => data),
+ *       method: afterRecomputation(submitForm, (formData) => formData),
  *       loader: async ({ params }) => {
  *         const response = await fetch('/api/submit', {
  *           method: 'POST',
@@ -155,86 +123,60 @@ type SignalSource<T> = Signal<T | undefined> & {
  *
  * 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
- * }
+ * // Mutation executes automatically when source emits
+ * store.setSubmitForm({ name: 'John', email: 'john@example.com' });
+ * // -> mutation loader executes with form data
+ * // Note: No store.mutateSubmit method exposed (source-based)
  * ```
  *
  * @example
- * Source for reload/refresh actions
+ * Binding async method to a source
  * ```ts
  * const { injectCraft } = craft(
  *   { name: '', providedIn: 'root' },
  *   craftSources({
- *     reload: source<void>(),
+ *     searchInput: source<string>(),
  *   }),
- *   craftQuery('data', ({ reload }) =>
- *     query(
- *       {
- *         params: () => ({}),
- *         loader: async () => {
- *           const response = await fetch('/api/data');
- *           return response.json();
- *         },
+ *   craftAsyncProcesses(({ searchInput }) => ({
+ *     search: asyncProcess({
+ *       method: afterRecomputation(searchInput, (term) => term),
+ *       loader: async ({ params }) => {
+ *         // Debounce at source level before setting
+ *         const response = await fetch(`/api/search?q=${params}`);
+ *         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>
+ * // Async method executes automatically
+ * store.setSearchInput('query');
+ * // -> search loader executes
  * ```
  *
  * @example
- * Multiple sources for different actions
+ * Extracting specific field from complex data
  * ```ts
+ * type FormData = {
+ *   user: { id: string; name: string };
+ *   address: { city: string };
+ * };
+ *
  * const { injectCraft } = craft(
  *   { name: '', providedIn: 'root' },
  *   craftSources({
- *     addTodo: source<{ text: string }>(),
- *     deleteTodo: source<string>(),
- *     toggleTodo: source<string>(),
+ *     formSubmit: source<FormData>(),
  *   }),
- *   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),
+ *   craftMutations(({ formSubmit }) => ({
+ *     updateUser: mutation({
+ *       // Extract only user data
+ *       method: afterRecomputation(formSubmit, (data) => data.user),
  *       loader: async ({ params }) => {
- *         const response = await fetch(`/api/todos/${params}/toggle`, {
+ *         const response = await fetch(`/api/users/${params.id}`, {
  *           method: 'PATCH',
+ *           body: JSON.stringify(params),
  *         });
  *         return response.json();
  *       },
@@ -244,267 +186,136 @@ type SignalSource<T> = Signal<T | undefined> & {
  *
  * const store = injectCraft();
  *
- * // Different actions trigger different mutations
- * store.setAddTodo({ text: 'Buy milk' });
- * store.setToggleTodo('todo-123');
- * store.setDeleteTodo('todo-456');
+ * // Only user data is passed to mutation
+ * store.setFormSubmit({
+ *   user: { id: 'user-1', name: 'John' },
+ *   address: { city: 'NYC' },
+ * });
+ * // -> mutation receives only { id: 'user-1', name: 'John' }
  * ```
  *
  * @example
- * Late listener with preserveLastValue
+ * Transforming data before execution
  * ```ts
- * const mySource = source<string>();
- *
- * // Early listener
- * const listener1 = computed(() => mySource());
- * console.log(listener1()); // undefined
+ * const { injectCraft } = craft(
+ *   { name: '', providedIn: 'root' },
+ *   craftSources({
+ *     searchParams: source<{ query: string; filters: string[] }>(),
+ *   }),
+ *   craftQuery('results', ({ searchParams }) =>
+ *     query({
+ *       method: afterRecomputation(searchParams, (params) => ({
+ *         q: params.query.trim().toLowerCase(),
+ *         f: params.filters.join(','),
+ *       })),
+ *       loader: async ({ params }) => {
+ *         const query = new URLSearchParams(params);
+ *         const response = await fetch(`/api/search?${query}`);
+ *         return response.json();
+ *       },
+ *     })
+ *   )
+ * );
  *
- * // Emit value
- * mySource.set('Hello');
- * console.log(listener1()); // 'Hello'
+ * const store = injectCraft();
  *
- * // 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
+ * // Data is transformed before query execution
+ * store.setSearchParams({
+ *   query: '  Angular  ',
+ *   filters: ['tutorial', 'advanced'],
  * });
- *
- * 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();
- *   }
- * }
+ * // -> query receives { q: 'angular', f: 'tutorial,advanced' }
  * ```
  *
  * @example
- * Source with complex payload
+ * Validation and type narrowing
  * ```ts
- * type SearchParams = {
- *   query: string;
- *   filters: string[];
- *   page: number;
- * };
- *
  * const { injectCraft } = craft(
  *   { name: '', providedIn: 'root' },
  *   craftSources({
- *     search: source<SearchParams>(),
+ *     inputChange: source<string>(),
  *   }),
- *   craftQuery('results', ({ search }) =>
- *     query({
- *       method: afterRecomputation(search, (params) => params),
+ *   craftAsyncProcesses(({ inputChange }) => ({
+ *     validate: asyncProcess({
+ *       method: afterRecomputation(inputChange, (input) => {
+ *         // Only proceed if input is valid
+ *         const trimmed = input.trim();
+ *         if (trimmed.length < 3) {
+ *           throw new Error('Input too short');
+ *         }
+ *         return trimmed;
+ *       }),
  *       loader: async ({ params }) => {
- *         const queryString = new URLSearchParams({
- *           q: params.query,
- *           filters: params.filters.join(','),
- *           page: String(params.page),
+ *         const response = await fetch('/api/validate', {
+ *           method: 'POST',
+ *           body: JSON.stringify({ input: params }),
  *         });
- *         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.
- *
- * This function binds queries, mutations, and async methods to sources for automatic execution by:
- * - Listening to source emissions and computing new values
- * - Providing a readonly source suitable for method binding
- * - Maintaining reactivity through Angular's effect system
- * - Enabling source-based triggering patterns
+ * // Invalid input throws error in callback
+ * store.setInputChange('ab'); // Error: Input too short
  *
- * @remarks
- * **Primary Use Case:**
- * Bind queries/mutations/async methods to sources for automatic execution:
- * ```ts
- * method: afterRecomputation(mySource, (data) => data)
+ * // Valid input proceeds
+ * store.setInputChange('valid input'); // Validation executes
  * ```
- * This pattern makes queries/mutations execute automatically when the source emits.
- *
- * **Execution Flow:**
- * 1. Source emits a value via `source.set(value)`
- * 2. afterRecomputation callback transforms the value
- * 3. Resulting readonly source emits the transformed value
- * 4. Bound query/mutation/async method executes with the new value
- *
- * **Difference from computedSource:**
- * - `afterRecomputation`: Designed for binding to method parameters
- * - `computedSource`: General-purpose source transformation
- * - Both transform source values, but afterRecomputation is optimized for method binding
- *
- * **Common Patterns:**
- * - **Identity transformation**: `afterRecomputation(source, (x) => x)` - pass value through
- * - **Field extraction**: `afterRecomputation(source, (data) => data.id)` - extract specific field
- * - **Validation**: `afterRecomputation(source, (data) => validate(data))` - transform and validate
- * - **Mapping**: `afterRecomputation(source, (data) => mapToDto(data))` - convert to different type
- *
- * @template State - The type of values produced by the callback
- * @template SourceType - The type of values emitted by the origin source
- *
- * @param _source - The source to listen to.
- *   When this source emits, the callback is invoked.
- *
- * @param callback - Function that transforms source values.
- *   Receives the emitted value and returns the transformed result.
- *
- * @returns A readonly source that emits transformed values.
- *   Can be used as the `method` parameter in queries, mutations, and async methods.
  *
  * @example
- * Binding a query to a source for automatic execution
+ * Multiple sources with different transformations
  * ```ts
  * const { injectCraft } = craft(
  *   { name: '', providedIn: 'root' },
  *   craftSources({
- *     userIdChange: source<string>(),
+ *     quickSearch: source<string>(),
+ *     advancedSearch: source<{ query: string; options: unknown }>(),
  *   }),
- *   craftQuery('user', ({ userIdChange }) =>
+ *   craftQuery('searchResults', ({ quickSearch, advancedSearch }) =>
  *     query({
- *       method: afterRecomputation(userIdChange, (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.setUserIdChange('user-123');
- * // -> query loader executes with params 'user-123'
- *
- * store.setUserIdChange('user-456');
- * // -> query loader executes again with params 'user-456'
- * ```
- *
- * @example
- * Binding a mutation to a source
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     submitForm: source<{ name: string; email: string }>(),
- *   }),
- *   craftMutations(({ submitForm }) => ({
- *     submit: mutation({
- *       method: afterRecomputation(submitForm, (formData) => formData),
+ *       method: afterRecomputation(
+ *         // Can combine sources at higher level
+ *         quickSearch, // For this example, using one source
+ *         (term) => ({ query: term, mode: 'quick' })
+ *       ),
  *       loader: async ({ params }) => {
- *         const response = await fetch('/api/submit', {
+ *         const response = await fetch('/api/search', {
  *           method: 'POST',
  *           body: JSON.stringify(params),
  *         });
  *         return response.json();
  *       },
- *     }),
- *   }))
+ *     })
+ *   )
  * );
  *
  * const store = injectCraft();
  *
- * // Mutation executes automatically when source emits
- * store.setSubmitForm({ name: 'John', email: 'john@example.com' });
- * // -> mutation loader executes with form data
- * // Note: No store.mutateSubmit method exposed (source-based)
+ * // Quick search with simple string
+ * store.setQuickSearch('angular');
+ * // -> query receives { query: 'angular', mode: 'quick' }
  * ```
  *
  * @example
- * Binding async method to a source
+ * Identity transformation (pass-through)
  * ```ts
  * const { injectCraft } = craft(
  *   { name: '', providedIn: 'root' },
  *   craftSources({
- *     searchInput: source<string>(),
+ *     dataUpdate: source<{ id: string; payload: unknown }>(),
  *   }),
- *   craftAsyncProcesses(({ searchInput }) => ({
- *     search: asyncProcess({
- *       method: afterRecomputation(searchInput, (term) => term),
+ *   craftMutations(({ dataUpdate }) => ({
+ *     update: mutation({
+ *       // Pass data through unchanged
+ *       method: afterRecomputation(dataUpdate, (data) => data),
  *       loader: async ({ params }) => {
- *         // Debounce at source level before setting
- *         const response = await fetch(`/api/search?q=${params}`);
+ *         const response = await fetch(`/api/data/${params.id}`, {
+ *           method: 'PUT',
+ *           body: JSON.stringify(params.payload),
+ *         });
  *         return response.json();
  *       },
  *     }),
@@ -513,185 +324,12 @@ declare function signalSource<T>(options?: {
  *
  * const store = injectCraft();
  *
- * // Async method executes automatically
- * store.setSearchInput('query');
- * // -> search loader executes
- * ```
- *
- * @example
- * Extracting specific field from complex data
- * ```ts
- * type FormData = {
- *   user: { id: string; name: string };
- *   address: { city: string };
- * };
- *
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     formSubmit: source<FormData>(),
- *   }),
- *   craftMutations(({ formSubmit }) => ({
- *     updateUser: mutation({
- *       // Extract only user data
- *       method: afterRecomputation(formSubmit, (data) => data.user),
- *       loader: async ({ params }) => {
- *         const response = await fetch(`/api/users/${params.id}`, {
- *           method: 'PATCH',
- *           body: JSON.stringify(params),
- *         });
- *         return response.json();
- *       },
- *     }),
- *   }))
- * );
- *
- * const store = injectCraft();
- *
- * // Only user data is passed to mutation
- * store.setFormSubmit({
- *   user: { id: 'user-1', name: 'John' },
- *   address: { city: 'NYC' },
- * });
- * // -> mutation receives only { id: 'user-1', name: 'John' }
- * ```
- *
- * @example
- * Transforming data before execution
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     searchParams: source<{ query: string; filters: string[] }>(),
- *   }),
- *   craftQuery('results', ({ searchParams }) =>
- *     query({
- *       method: afterRecomputation(searchParams, (params) => ({
- *         q: params.query.trim().toLowerCase(),
- *         f: params.filters.join(','),
- *       })),
- *       loader: async ({ params }) => {
- *         const query = new URLSearchParams(params);
- *         const response = await fetch(`/api/search?${query}`);
- *         return response.json();
- *       },
- *     })
- *   )
- * );
- *
- * const store = injectCraft();
- *
- * // Data is transformed before query execution
- * store.setSearchParams({
- *   query: '  Angular  ',
- *   filters: ['tutorial', 'advanced'],
- * });
- * // -> query receives { q: 'angular', f: 'tutorial,advanced' }
- * ```
- *
- * @example
- * Validation and type narrowing
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     inputChange: source<string>(),
- *   }),
- *   craftAsyncProcesses(({ inputChange }) => ({
- *     validate: asyncProcess({
- *       method: afterRecomputation(inputChange, (input) => {
- *         // Only proceed if input is valid
- *         const trimmed = input.trim();
- *         if (trimmed.length < 3) {
- *           throw new Error('Input too short');
- *         }
- *         return trimmed;
- *       }),
- *       loader: async ({ params }) => {
- *         const response = await fetch('/api/validate', {
- *           method: 'POST',
- *           body: JSON.stringify({ input: params }),
- *         });
- *         return response.json();
- *       },
- *     }),
- *   }))
- * );
- *
- * const store = injectCraft();
- *
- * // Invalid input throws error in callback
- * store.setInputChange('ab'); // Error: Input too short
- *
- * // Valid input proceeds
- * store.setInputChange('valid input'); // Validation executes
- * ```
- *
- * @example
- * Multiple sources with different transformations
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     quickSearch: source<string>(),
- *     advancedSearch: source<{ query: string; options: unknown }>(),
- *   }),
- *   craftQuery('searchResults', ({ quickSearch, advancedSearch }) =>
- *     query({
- *       method: afterRecomputation(
- *         // Can combine sources at higher level
- *         quickSearch, // For this example, using one source
- *         (term) => ({ query: term, mode: 'quick' })
- *       ),
- *       loader: async ({ params }) => {
- *         const response = await fetch('/api/search', {
- *           method: 'POST',
- *           body: JSON.stringify(params),
- *         });
- *         return response.json();
- *       },
- *     })
- *   )
- * );
- *
- * const store = injectCraft();
- *
- * // Quick search with simple string
- * store.setQuickSearch('angular');
- * // -> query receives { query: 'angular', mode: 'quick' }
- * ```
- *
- * @example
- * Identity transformation (pass-through)
- * ```ts
- * const { injectCraft } = craft(
- *   { name: '', providedIn: 'root' },
- *   craftSources({
- *     dataUpdate: source<{ id: string; payload: unknown }>(),
- *   }),
- *   craftMutations(({ dataUpdate }) => ({
- *     update: mutation({
- *       // Pass data through unchanged
- *       method: afterRecomputation(dataUpdate, (data) => data),
- *       loader: async ({ params }) => {
- *         const response = await fetch(`/api/data/${params.id}`, {
- *           method: 'PUT',
- *           body: JSON.stringify(params.payload),
- *         });
- *         return response.json();
- *       },
- *     }),
- *   }))
- * );
- *
- * const store = injectCraft();
- *
- * // Data passed through unchanged
- * store.setDataUpdate({ id: 'item-1', payload: { value: 123 } });
- * // -> mutation receives exact same object
+ * // Data passed through unchanged
+ * store.setDataUpdate({ id: 'item-1', payload: { value: 123 } });
+ * // -> 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>;