@craft-ts/core 0.7.0-beta.13

package/src/lib/signal-source.js

@@ -0,0 +1,433 @@
+import { assertInInjectionContext, DestroyRef, inject, Injector, linkedSignal, runInInjectionContext, signal, } from './host/craft-compat';
+import { takeUntilDestroyed } from './host/craft-compat';
+import { SourceBranded } from './util/util';
+import { ɵcreateHostTaggedInjector, ɵHOST_TAG_LIST } from './craft-service';
+import { APP_SNAPSHOT_REGISTRY } from './take-app-snapshot';
+import { injectFnWrapper } from './fn-wrapper';
+import { RAW_REACTIVE_VALUE, REACTIVE_VALUE_TYPE, YIELDABLE_VALUE, } from './reactive-read';
+/**
+ * Creates a source for event-driven communication with lazy emission semantics.
+ *
+ * Sources are the foundation of event-driven patterns in craft-ts, 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 name - Name matching the variable/property this source is assigned to (used for host
+ * tagging and dev-tools snapshot reporting, consistent with `craftComputed`/`craftEffect`)
+ * @param options - Optional configuration:
+ *   - `equal`: Custom equality function for change detection (prevents duplicate emissions)
+ *
+ * @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 { UserStore } = craftService(
+ *   { name: 'UserStore', providedIn: 'toProvide' },
+ *   function* () {
+ *     const loadUser = signalSource<string>('loadUser');
+ *
+ *     const user = yield* query({
+ *       method: afterRecomputation(loadUser, (userId) => userId),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch(`/api/users/${params}`);
+ *         return response.json();
+ *       },
+ *     });
+ *
+ *     return { loadUser, user };
+ *   },
+ * );
+ *
+ * const store = UserStore();
+ *
+ * // Query executes automatically when source emits
+ * store.loadUser.set('user-123');
+ * // -> loadUser source emits 'user-123'
+ * // -> user query executes with params 'user-123'
+ *
+ * store.loadUser.set('user-456');
+ * // -> user query executes again with params 'user-456'
+ * ```
+ *
+ * @example
+ * Source for form submission
+ * ```ts
+ * type FormData = { name: string; email: string };
+ *
+ * const { FormStore } = craftService(
+ *   { name: 'FormStore', providedIn: 'toProvide' },
+ *   function* () {
+ *     const submitForm = signalSource<FormData>('submitForm');
+ *
+ *     const submit = yield* mutation({
+ *       method: afterRecomputation(submitForm, (data) => data),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch('/api/submit', {
+ *           method: 'POST',
+ *           body: JSON.stringify(params),
+ *         });
+ *         return response.json();
+ *       },
+ *     });
+ *
+ *     return { submitForm, submit };
+ *   },
+ * );
+ *
+ * const store = FormStore();
+ *
+ * // 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.submitForm.set(this.formData);
+ *   // -> submitForm source emits
+ *   // -> submit mutation executes
+ * }
+ * ```
+ *
+ * @example
+ * Source for reload/refresh actions
+ * ```ts
+ * const { DataStore } = craftService(
+ *   { name: 'DataStore', providedIn: 'toProvide' },
+ *   function* () {
+ *     const reload = signalSource<void>('reload');
+ *
+ *     const data = yield* query({
+ *       method: afterRecomputation(reload, () => ({})),
+ *       loader: async () => {
+ *         const response = await fetch('/api/data');
+ *         return response.json();
+ *       },
+ *     });
+ *
+ *     return { reload, data };
+ *   },
+ * );
+ *
+ * const store = DataStore();
+ *
+ * // Trigger reload from anywhere
+ * store.reload.set();
+ * // -> reload source emits
+ * // -> query re-executes
+ *
+ * // In component:
+ * // <button (click)="store.reload.set()">Refresh</button>
+ * ```
+ *
+ * @example
+ * Multiple sources for different actions
+ * ```ts
+ * const { TodoStore } = craftService(
+ *   { name: 'TodoStore', providedIn: 'toProvide' },
+ *   function* () {
+ *     const addTodo = signalSource<{ text: string }>('addTodo');
+ *     const deleteTodo = signalSource<string>('deleteTodo');
+ *     const toggleTodo = signalSource<string>('toggleTodo');
+ *
+ *     const create = yield* mutation({
+ *       method: afterRecomputation(addTodo, (data) => data),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch('/api/todos', {
+ *           method: 'POST',
+ *           body: JSON.stringify(params),
+ *         });
+ *         return response.json();
+ *       },
+ *     });
+ *
+ *     const remove = yield* mutation({
+ *       method: afterRecomputation(deleteTodo, (id) => id),
+ *       loader: async ({ params }) => {
+ *         await fetch(`/api/todos/${params}`, { method: 'DELETE' });
+ *         return { deleted: true };
+ *       },
+ *     });
+ *
+ *     const toggle = yield* mutation({
+ *       method: afterRecomputation(toggleTodo, (id) => id),
+ *       loader: async ({ params }) => {
+ *         const response = await fetch(`/api/todos/${params}/toggle`, {
+ *           method: 'PATCH',
+ *         });
+ *         return response.json();
+ *       },
+ *     });
+ *
+ *     return { addTodo, deleteTodo, toggleTodo, create, remove, toggle };
+ *   },
+ * );
+ *
+ * const store = TodoStore();
+ *
+ * // Different actions trigger different mutations
+ * store.addTodo.set({ text: 'Buy milk' });
+ * store.toggleTodo.set('todo-123');
+ * store.deleteTodo.set('todo-456');
+ * ```
+ *
+ * @example
+ * Late listener with preserveLastValue
+ * ```ts
+ * // Inside a component constructor or a craftService factory (injection context)
+ * const mySource = signalSource<string>('mySource');
+ *
+ * // 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 };
+ *
+ * // Inside a component constructor or a craftService factory (injection context)
+ * const paramsSource = signalSource<Params>('paramsSource', {
+ *   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
+ * // Root-provided coordinator service, injected wherever the shared source is needed
+ * const { RefreshCoordinator } = craftService(
+ *   { name: 'RefreshCoordinator', scope: 'root' },
+ *   () => {
+ *     const refreshAllSource = signalSource<void>('refreshAllSource');
+ *     return { refreshAllSource };
+ *   },
+ * );
+ *
+ * // Component A's store
+ * const { DataViewStore, provideDataViewStore } = craftService(
+ *   { name: 'DataViewStore', providedIn: 'toProvide' },
+ *   function* () {
+ *     const { refreshAllSource } = RefreshCoordinator();
+ *
+ *     const data = yield* query({
+ *       method: afterRecomputation(refreshAllSource, () => ({})),
+ *       loader: async () => {
+ *         const response = await fetch('/api/data');
+ *         return response.json();
+ *       },
+ *     });
+ *
+ *     return { data };
+ *   },
+ * );
+ *
+ * @Component({
+ *   selector: 'app-data-view',
+ *   template: '...',
+ *   providers: [provideDataViewStore()],
+ * })
+ * export class DataViewComponent {
+ *   store = DataViewStore();
+ * }
+ *
+ * // Component B
+ * @Component({
+ *   selector: 'app-refresh-button',
+ *   template: '<button (click)="refresh()">Refresh All</button>',
+ * })
+ * export class RefreshButtonComponent {
+ *   private readonly coordinator = RefreshCoordinator();
+ *
+ *   refresh() {
+ *     // Triggers refresh in every store listening to this source
+ *     this.coordinator.refreshAllSource.set();
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Source with complex payload
+ * ```ts
+ * type SearchParams = {
+ *   query: string;
+ *   filters: string[];
+ *   page: number;
+ * };
+ *
+ * const { SearchStore } = craftService(
+ *   { name: 'SearchStore', providedIn: 'toProvide' },
+ *   function* () {
+ *     const search = signalSource<SearchParams>('search');
+ *
+ *     const results = yield* 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();
+ *       },
+ *     });
+ *
+ *     return { search, results };
+ *   },
+ * );
+ *
+ * const store = SearchStore();
+ *
+ * // Emit complex search parameters
+ * store.search.set({
+ *   query: 'angular',
+ *   filters: ['tutorial', 'advanced'],
+ *   page: 1,
+ * });
+ * ```
+ */
+export function signalSource(name, options) {
+    assertInInjectionContext(signalSource);
+    const injector = inject(Injector);
+    const sourceInjector = ɵcreateHostTaggedInjector(injector, `signal-source:${name}`);
+    const destroyRef = inject(DestroyRef);
+    const sourceState = signal(undefined, {
+        ...(options?.equal && { equal: options?.equal }), // add the equal function here, it may helps to detect changes when using scalar values
+        debugName: `${name}_sourceState`,
+    });
+    const wrappedSet = runInInjectionContext(sourceInjector, () => injectFnWrapper()((value) => sourceState.set(value)));
+    const set = (value) => runInInjectionContext(sourceInjector, () => wrappedSet(value));
+    const listener = (listenerOptions) => linkedSignal({
+        source: sourceState,
+        computation: (currentSourceState, previousData) => {
+            // always when first listened return undefined
+            if (!previousData && listenerOptions?.nullishFirstValue !== false) {
+                return undefined;
+            }
+            return currentSourceState;
+        },
+        ...(options?.equal && { equal: options?.equal }),
+        debugName: name,
+    });
+    const result = listener({
+        nullishFirstValue: true,
+    });
+    const registry = inject(APP_SNAPSHOT_REGISTRY, { optional: true });
+    if (registry) {
+        const from = sourceInjector.get(ɵHOST_TAG_LIST, null) ?? [];
+        registry.triggerSnapshot$
+            .pipe(takeUntilDestroyed(destroyRef))
+            .subscribe(() => {
+            let stateSnapshot;
+            try {
+                stateSnapshot = result();
+            }
+            catch (error) {
+                stateSnapshot = {
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+            registry.allSnapShot$.next({
+                source: name,
+                from,
+                state: stateSnapshot,
+            });
+        });
+    }
+    return Object.assign(result, {
+        preserveLastValue: listener({
+            nullishFirstValue: false,
+        }),
+        set,
+    }, SourceBranded);
+}
+//# sourceMappingURL=signal-source.js.map

package/src/lib/signal-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-source.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/signal-source.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  assertInInjectionContext,\n  DestroyRef,\n  inject,\n  Injector,\n  linkedSignal,\n  runInInjectionContext,\n  Signal,\n  signal,\n  ValueEqualityFn,\n} from './host/craft-compat';\nimport { takeUntilDestroyed } from './host/craft-compat';\nimport { SourceBranded } from './util/util';\nimport { ɵcreateHostTaggedInjector, ɵHOST_TAG_LIST } from './craft-service';\nimport { APP_SNAPSHOT_REGISTRY } from './take-app-snapshot';\nimport { injectFnWrapper } from './fn-wrapper';\nimport {\n  RAW_REACTIVE_VALUE,\n  REACTIVE_VALUE_TYPE,\n  YIELDABLE_VALUE,\n  type ReactiveReadRequest,\n  type YieldableReactiveValue,\n} from './reactive-read';\n\ntype YieldableSignalSourceValue<T> = YieldableReactiveValue<\n  T | undefined,\n  string\n>;\n\ntype YieldableSignalSourceMetadata<T> = Omit<\n  YieldableSignalSourceValue<T>,\n  | typeof RAW_REACTIVE_VALUE\n  | typeof REACTIVE_VALUE_TYPE\n  | typeof YIELDABLE_VALUE\n> & {\n  readonly [RAW_REACTIVE_VALUE]: YieldableSignalSourceValue<T>[typeof RAW_REACTIVE_VALUE];\n  readonly [REACTIVE_VALUE_TYPE]: T | undefined;\n  readonly [YIELDABLE_VALUE]: string;\n};\n\ntype SignalSourceReader<T> = {\n  (): T | undefined;\n  (): Generator<ReactiveReadRequest<T | undefined>, T | undefined, unknown>;\n} & YieldableSignalSourceMetadata<T>;\n\nexport type SignalSource<T> = SignalSourceReader<T> & {\n  set: (value: T) => void;\n  preserveLastValue: SignalSourceReader<T>;\n} & SourceBranded;\n\n/**\n * Creates a source for event-driven communication with lazy emission semantics.\n *\n * Sources are the foundation of event-driven patterns in craft-ts, enabling:\n * - Discrete event emissions (unlike continuous signals)\n * - Lazy behavior (undefined until explicitly set)\n * - Decoupled communication between components and stores\n * - Automatic triggering of queries, mutations, and async methods\n * - Multi-listener support with independent subscription timing\n *\n * @remarks\n * **Core Concept:**\n * Sources implement event emitter pattern with reactive semantics:\n * - Emit only when explicitly set (not on every read like signals)\n * - Listeners receive `undefined` on first read (lazy semantics)\n * - New listeners don't receive previous emissions by default\n * - Use `preserveLastValue` to get the last emitted value immediately\n *\n * **Difference from Signals:**\n * - **Signals**: Always have a value, recompute on access, continuous state\n * - **Sources**: Emit on explicit set, lazy by default, discrete events\n * - Sources are for events/actions, signals are for state\n *\n * **Use Cases:**\n * - **User actions**: Button clicks, form submissions, custom events\n * - **Navigation events**: Route changes, tab switches\n * - **Data events**: Reload triggers, refresh requests\n * - **Coordination**: Communication between disconnected components\n * - **Store inputs**: Triggering queries/mutations from components\n * - **Event buses**: Decoupled event communication\n *\n * **Integration with Queries/Mutations:**\n * - Bind to method using `afterRecomputation(source, callback)`\n * - Query/mutation executes automatically when source emits\n * - No manual method exposed (source-based triggering)\n *\n * **Listener Semantics:**\n * - **Standard listener**: Returns `undefined` until source emits, then returns new values only\n * - **preserveLastValue**: Returns last emitted value immediately, then tracks new values\n * - Useful for late subscribers that need current state\n *\n * **Limitations:**\n * Sources are signals and behave differently from observables.\n * Understanding these three key limitations is important:\n * - **Multiple sets in same cycle**: When a source is set multiple times during the same cycle\n *   (between the first set and the Change Detection that executes all consumer callbacks),\n *   consumers will only react once during CD and will only see the last set value.\n *   Intermediate values are discarded.\n * - **Multiple sources order**: Within the same cycle, if multiple sources are triggered,\n *   consumers cannot determine the order in which the sources were set.\n *   The original emission sequence is not preserved.\n * - **Consumer execution order**: When multiple sources are triggered in the same cycle,\n *   consumer callbacks are invoked in the order they were declared, not in the order\n *   their source producers were triggered.\n * - **No synchronous intermediate value reactions**: Unlike observables, sources cannot react\n *   to each intermediate value synchronously. A mechanism similar to observables\n *   (or using native Observable API) without RxJS is being considered to enable\n *   synchronous reactions to intermediate values, matching the behavior currently\n *   offered by observables.\n *\n * @template T - The type of values emitted by the source\n *\n * @param name - Name matching the variable/property this source is assigned to (used for host\n * tagging and dev-tools snapshot reporting, consistent with `craftComputed`/`craftEffect`)\n * @param options - Optional configuration:\n *   - `equal`: Custom equality function for change detection (prevents duplicate emissions)\n *\n * @returns A source object with:\n *   - `()`: Read current value (undefined until first emission)\n *   - `set(value)`: Emit a value to all listeners\n *   - `preserveLastValue`: Alternative signal that returns last value immediately\n *\n * @example\n * Basic source for user actions\n * ```ts\n * const { UserStore } = craftService(\n *   { name: 'UserStore', providedIn: 'toProvide' },\n *   function* () {\n *     const loadUser = signalSource<string>('loadUser');\n *\n *     const user = yield* query({\n *       method: afterRecomputation(loadUser, (userId) => userId),\n *       loader: async ({ params }) => {\n *         const response = await fetch(`/api/users/${params}`);\n *         return response.json();\n *       },\n *     });\n *\n *     return { loadUser, user };\n *   },\n * );\n *\n * const store = UserStore();\n *\n * // Query executes automatically when source emits\n * store.loadUser.set('user-123');\n * // -> loadUser source emits 'user-123'\n * // -> user query executes with params 'user-123'\n *\n * store.loadUser.set('user-456');\n * // -> user query executes again with params 'user-456'\n * ```\n *\n * @example\n * Source for form submission\n * ```ts\n * type FormData = { name: string; email: string };\n *\n * const { FormStore } = craftService(\n *   { name: 'FormStore', providedIn: 'toProvide' },\n *   function* () {\n *     const submitForm = signalSource<FormData>('submitForm');\n *\n *     const submit = yield* mutation({\n *       method: afterRecomputation(submitForm, (data) => data),\n *       loader: async ({ params }) => {\n *         const response = await fetch('/api/submit', {\n *           method: 'POST',\n *           body: JSON.stringify(params),\n *         });\n *         return response.json();\n *       },\n *     });\n *\n *     return { submitForm, submit };\n *   },\n * );\n *\n * const store = FormStore();\n *\n * // In component template:\n * // <form (submit)=\"onSubmit()\">\n * //   <input name=\"name\" [(ngModel)]=\"formData.name\" />\n * //   <input name=\"email\" [(ngModel)]=\"formData.email\" />\n * // </form>\n *\n * onSubmit() {\n *   // Mutation executes automatically\n *   this.store.submitForm.set(this.formData);\n *   // -> submitForm source emits\n *   // -> submit mutation executes\n * }\n * ```\n *\n * @example\n * Source for reload/refresh actions\n * ```ts\n * const { DataStore } = craftService(\n *   { name: 'DataStore', providedIn: 'toProvide' },\n *   function* () {\n *     const reload = signalSource<void>('reload');\n *\n *     const data = yield* query({\n *       method: afterRecomputation(reload, () => ({})),\n *       loader: async () => {\n *         const response = await fetch('/api/data');\n *         return response.json();\n *       },\n *     });\n *\n *     return { reload, data };\n *   },\n * );\n *\n * const store = DataStore();\n *\n * // Trigger reload from anywhere\n * store.reload.set();\n * // -> reload source emits\n * // -> query re-executes\n *\n * // In component:\n * // <button (click)=\"store.reload.set()\">Refresh</button>\n * ```\n *\n * @example\n * Multiple sources for different actions\n * ```ts\n * const { TodoStore } = craftService(\n *   { name: 'TodoStore', providedIn: 'toProvide' },\n *   function* () {\n *     const addTodo = signalSource<{ text: string }>('addTodo');\n *     const deleteTodo = signalSource<string>('deleteTodo');\n *     const toggleTodo = signalSource<string>('toggleTodo');\n *\n *     const create = yield* mutation({\n *       method: afterRecomputation(addTodo, (data) => data),\n *       loader: async ({ params }) => {\n *         const response = await fetch('/api/todos', {\n *           method: 'POST',\n *           body: JSON.stringify(params),\n *         });\n *         return response.json();\n *       },\n *     });\n *\n *     const remove = yield* mutation({\n *       method: afterRecomputation(deleteTodo, (id) => id),\n *       loader: async ({ params }) => {\n *         await fetch(`/api/todos/${params}`, { method: 'DELETE' });\n *         return { deleted: true };\n *       },\n *     });\n *\n *     const toggle = yield* mutation({\n *       method: afterRecomputation(toggleTodo, (id) => id),\n *       loader: async ({ params }) => {\n *         const response = await fetch(`/api/todos/${params}/toggle`, {\n *           method: 'PATCH',\n *         });\n *         return response.json();\n *       },\n *     });\n *\n *     return { addTodo, deleteTodo, toggleTodo, create, remove, toggle };\n *   },\n * );\n *\n * const store = TodoStore();\n *\n * // Different actions trigger different mutations\n * store.addTodo.set({ text: 'Buy milk' });\n * store.toggleTodo.set('todo-123');\n * store.deleteTodo.set('todo-456');\n * ```\n *\n * @example\n * Late listener with preserveLastValue\n * ```ts\n * // Inside a component constructor or a craftService factory (injection context)\n * const mySource = signalSource<string>('mySource');\n *\n * // Early listener\n * const listener1 = computed(() => mySource());\n * console.log(listener1()); // undefined\n *\n * // Emit value\n * mySource.set('Hello');\n * console.log(listener1()); // 'Hello'\n *\n * // Late listener (after emission)\n * const listener2 = computed(() => mySource());\n * console.log(listener2()); // undefined (doesn't get previous emission)\n *\n * mySource.set('World');\n * console.log(listener1()); // 'World'\n * console.log(listener2()); // 'World'\n *\n * // Using preserveLastValue for late listeners\n * const listener3 = computed(() => mySource.preserveLastValue());\n * console.log(listener3()); // 'World' (gets last value immediately)\n * ```\n *\n * @example\n * Custom equality to prevent duplicate emissions\n * ```ts\n * type Params = { id: string; timestamp: number };\n *\n * // Inside a component constructor or a craftService factory (injection context)\n * const paramsSource = signalSource<Params>('paramsSource', {\n *   equal: (a, b) => a?.id === b?.id, // Compare only by id\n * });\n *\n * const listener = computed(() => paramsSource());\n *\n * paramsSource.set({ id: 'item-1', timestamp: Date.now() });\n * // -> listener receives value\n *\n * paramsSource.set({ id: 'item-1', timestamp: Date.now() });\n * // -> listener does NOT receive value (same id)\n *\n * paramsSource.set({ id: 'item-2', timestamp: Date.now() });\n * // -> listener receives value (different id)\n * ```\n *\n * @example\n * Source for coordinating multiple components\n * ```ts\n * // Root-provided coordinator service, injected wherever the shared source is needed\n * const { RefreshCoordinator } = craftService(\n *   { name: 'RefreshCoordinator', scope: 'root' },\n *   () => {\n *     const refreshAllSource = signalSource<void>('refreshAllSource');\n *     return { refreshAllSource };\n *   },\n * );\n *\n * // Component A's store\n * const { DataViewStore, provideDataViewStore } = craftService(\n *   { name: 'DataViewStore', providedIn: 'toProvide' },\n *   function* () {\n *     const { refreshAllSource } = RefreshCoordinator();\n *\n *     const data = yield* query({\n *       method: afterRecomputation(refreshAllSource, () => ({})),\n *       loader: async () => {\n *         const response = await fetch('/api/data');\n *         return response.json();\n *       },\n *     });\n *\n *     return { data };\n *   },\n * );\n *\n * @Component({\n *   selector: 'app-data-view',\n *   template: '...',\n *   providers: [provideDataViewStore()],\n * })\n * export class DataViewComponent {\n *   store = DataViewStore();\n * }\n *\n * // Component B\n * @Component({\n *   selector: 'app-refresh-button',\n *   template: '<button (click)=\"refresh()\">Refresh All</button>',\n * })\n * export class RefreshButtonComponent {\n *   private readonly coordinator = RefreshCoordinator();\n *\n *   refresh() {\n *     // Triggers refresh in every store listening to this source\n *     this.coordinator.refreshAllSource.set();\n *   }\n * }\n * ```\n *\n * @example\n * Source with complex payload\n * ```ts\n * type SearchParams = {\n *   query: string;\n *   filters: string[];\n *   page: number;\n * };\n *\n * const { SearchStore } = craftService(\n *   { name: 'SearchStore', providedIn: 'toProvide' },\n *   function* () {\n *     const search = signalSource<SearchParams>('search');\n *\n *     const results = yield* query({\n *       method: afterRecomputation(search, (params) => params),\n *       loader: async ({ params }) => {\n *         const queryString = new URLSearchParams({\n *           q: params.query,\n *           filters: params.filters.join(','),\n *           page: String(params.page),\n *         });\n *         const response = await fetch(`/api/search?${queryString}`);\n *         return response.json();\n *       },\n *     });\n *\n *     return { search, results };\n *   },\n * );\n *\n * const store = SearchStore();\n *\n * // Emit complex search parameters\n * store.search.set({\n *   query: 'angular',\n *   filters: ['tutorial', 'advanced'],\n *   page: 1,\n * });\n * ```\n */\nexport function signalSource<T>(\n  name: string,\n  options?: {\n    equal?: ValueEqualityFn<NoInfer<T> | undefined>;\n  },\n): SignalSource<T> {\n  assertInInjectionContext(signalSource);\n  const injector = inject(Injector);\n  const sourceInjector = ɵcreateHostTaggedInjector(\n    injector,\n    `signal-source:${name}`,\n  );\n  const destroyRef = inject(DestroyRef);\n\n  const sourceState = signal<T | undefined>(undefined, {\n    ...(options?.equal && { equal: options?.equal }), // add the equal function here, it may helps to detect changes when using scalar values\n    debugName: `${name}_sourceState`,\n  });\n\n  const wrappedSet = runInInjectionContext(sourceInjector, () =>\n    injectFnWrapper()((value: T) => sourceState.set(value)),\n  );\n  const set = (value: T) =>\n    runInInjectionContext(sourceInjector, () => wrappedSet(value));\n\n  const listener = (listenerOptions: { nullishFirstValue?: boolean }) =>\n    linkedSignal<T, T | undefined>({\n      source: sourceState as Signal<T>,\n      computation: (currentSourceState, previousData) => {\n        // always when first listened return undefined\n        if (!previousData && listenerOptions?.nullishFirstValue !== false) {\n          return undefined;\n        }\n        return currentSourceState;\n      },\n      ...(options?.equal && { equal: options?.equal }),\n      debugName: name,\n    });\n\n  const result = listener({\n    nullishFirstValue: true,\n  });\n\n  const registry = inject(APP_SNAPSHOT_REGISTRY, { optional: true });\n  if (registry) {\n    const from = sourceInjector.get(ɵHOST_TAG_LIST, null) ?? [];\n    registry.triggerSnapshot$\n      .pipe(takeUntilDestroyed(destroyRef))\n      .subscribe(() => {\n        let stateSnapshot: unknown;\n        try {\n          stateSnapshot = result();\n        } catch (error) {\n          stateSnapshot = {\n            error: error instanceof Error ? error.message : String(error),\n          };\n        }\n        registry.allSnapShot$.next({\n          source: name,\n          from,\n          state: stateSnapshot,\n        });\n      });\n  }\n\n  return Object.assign(\n    result,\n    {\n      preserveLastValue: listener({\n        nullishFirstValue: false,\n      }),\n      set,\n    },\n    SourceBranded,\n  ) as unknown as SignalSource<T>;\n}\n"]}

package/src/lib/source$.d.ts

@@ -0,0 +1,121 @@
+import { EventEmitter, Signal } from './host/craft-compat';
+import type { SERVICE_HELPER_DEPENDENCIES, ServiceDependencies } from './craft-service';
+import { type NamedCraftPrimitiveGen } from './craft-primitive-gen';
+export type SourceDependency<Name extends string> = {
+    [K in Name]: ServiceDependencies<'function', {}>;
+};
+type SourceDependencyCarrier<Name extends string> = {
+    readonly [SERVICE_HELPER_DEPENDENCIES]?: SourceDependency<Name>;
+};
+export type SourceSubscribe<T> = {
+    subscribe: (callback: (value: T) => void) => ReturnType<EventEmitter<T>['subscribe']>;
+};
+export type SourceInstance<T, Name extends string = string> = SourceDependencyCarrier<Name> & {
+    emit: (value: T) => void;
+    subscribe: (callback: (value: T) => void) => ReturnType<EventEmitter<T>['subscribe']>;
+    asReadonly: () => ReadonlySource$<T, Name>;
+    preserveLastValue: () => PreservedSource$<T, Name>;
+    value: Signal<T | undefined>;
+};
+export type Source$<T, Name extends string = string> = SourceInstance<T, Name> & NamedCraftPrimitiveGen<Name, SourceInstance<T, Name>>;
+export type PreservedSource$<T, Name extends string = string> = SourceDependencyCarrier<Name> & {
+    emit: (value: T) => void;
+    subscribe: (callback: (value: T) => void) => void;
+    asReadonly: () => ReadonlySource$<T, Name>;
+    value: Signal<T | undefined>;
+};
+export type ReadonlySource$<T, Name extends string = string> = SourceDependencyCarrier<Name> & {
+    subscribe: (callback: (value: T) => void) => ReturnType<EventEmitter<T>['subscribe']>;
+    value: Signal<T | undefined>;
+};
+/**
+ * Creates an event emitter with automatic cleanup and signal-based value tracking.
+ *
+ * `source$` provides a lightweight event streaming solution that combines event emission,
+ * automatic subscription cleanup via `DestroyRef`, and signal-based reactive value tracking.
+ *
+ * @template T - The type of values emitted by the source
+ *
+ * @param name - Name matching the variable/property this source is assigned to (used for host
+ * tagging and dev-tools snapshot reporting, consistent with `craftComputed`/`craftEffect`)
+ *
+ * @returns {Source$<T>} A source object that is also a named primitive
+ * generator. Use it directly with `emit()`/`subscribe()`, or consume it with
+ * `yield*` to obtain `{ [name]: source }` and propagate its dependency metadata.
+ * - `emit(value: T)` - Emits a value to all subscribers and updates the internal signal
+ * - `subscribe(callback: (value: T) => void)` - Subscribes to emissions with automatic cleanup
+ * - `value: Signal<T | undefined>` - A read-only signal containing the last emitted value
+ * - `asReadonly()` - Returns a read-only version (only `subscribe` and `value`)
+ * - `preserveLastValue()` - Returns a variant that immediately emits the last value to new subscribers
+ *
+ * @example
+ * Yieldable source service
+ * ```typescript
+ * const { Reset } = craftService(
+ *   { name: 'Reset', providedIn: 'global' },
+ *   function* () {
+ *     const reset$ = yield* source$<void>('reset$');
+ *     return reset$;
+ *   },
+ * );
+ *
+ * const reset = yield* Reset();
+ * reset.emit();
+ * ```
+ *
+ * @example
+ * Basic usage with state coordination
+ * ```typescript
+ * import { source$, state, on$ } from '@craft-ts/core';
+ *
+ * @Component({
+ *   selector: 'app-counter',
+ *   template: `
+ *     <p>Count: {{ counter() }}</p>
+ *     <button (click)="counter.increment()">+1</button>
+ *     <button (click)="reset$.emit()">Reset</button>
+ *   `,
+ * })
+ * export class CounterComponent {
+ *   reset$ = source$<void>('reset$');
+ *
+ *   counter = craftUse(state(0, ({ set, update }) => ({
+ *     increment: () => update((v) => v + 1),
+ *     reset: on$(this.reset$, () => set(0)),
+ *   })));
+ * }
+ * ```
+ *
+ *
+ * @example
+ * Late subscriber with preserved last value
+ * ```typescript
+ * const notifications$ = source$<string>('notifications$').preserveLastValue();
+ *
+ * notifications$.emit('Server started');
+ * notifications$.emit('Database connected');
+ *
+ * // Late subscriber receives the last value immediately
+ * notifications$.subscribe((msg) => {
+ *   console.log(msg); // 'Database connected'
+ * });
+ * ```
+ *
+ * @example
+ * Read-only access pattern
+ * ```typescript
+ * class DataService {
+ *   private dataUpdated$ = source$<Data>('dataUpdated$');
+ *   readonly dataUpdated = this.dataUpdated$.asReadonly();
+ *
+ *   updateData(data: Data) {
+ *     this.dataUpdated$.emit(data);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://craft-ts.dev/utils/source$ | source$ documentation}
+ */
+export declare function source$<T, Name extends string = string>(name: Name): Source$<T, Name>;
+export {};
+//# sourceMappingURL=source$.d.ts.map

package/src/lib/source$.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source$.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/source$.ts"],"names":[],"mappings":"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"}