@signality/core 0.0.1-alpha.2

package/router/route-data/index.d.ts

@@ -0,0 +1,28 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type RouteDataOptions<T = unknown> = CreateSignalOptions<T> & WithInjector;
+/**
+ * Reactive wrapper around the [Angular Router](https://angular.dev/guide/routing) route data.
+ *
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal containing the current route data
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div>
+ *       <h1>{{ data().name }}</h1>
+ *       @if (data().showBreadcrumbs) {
+ *         <nav>Breadcrumbs here</nav>
+ *       }
+ *     </div>
+ *   `
+ * })
+ * class ProductComponent {
+ *   // Route with data: { name: 'Product Page', showBreadcrumbs: true }
+ *   readonly data = routeData<{ name: string; showBreadcrumbs: boolean }>();
+ * }
+ * ```
+ */
+export declare function routeData<T = unknown>(options?: RouteDataOptions<T>): Signal<T>;

package/router/router-listener/index.d.ts

@@ -0,0 +1,83 @@
+import { ActivationEnd, ActivationStart, ChildActivationEnd, ChildActivationStart, GuardsCheckEnd, GuardsCheckStart, NavigationCancel, NavigationEnd, NavigationError, NavigationSkipped, NavigationStart, ResolveEnd, ResolveStart, RouteConfigLoadEnd, RouteConfigLoadStart, RoutesRecognized, Scroll } from '@angular/router';
+import type { WithInjector } from '@signality/core/types';
+export interface RouterListenerOptions extends WithInjector {
+    /** If true, automatically unsubscribe after the first event */
+    readonly once?: boolean;
+}
+export interface RouterListenerRef {
+    /** Manually unsubscribe from router events */
+    readonly destroy: () => void;
+}
+export type RouterEventType = 'navigationstart' | 'navigationend' | 'navigationcancel' | 'navigationerror' | 'navigationskipped' | 'routesrecognized' | 'guardscheckstart' | 'guardscheckend' | 'resolvestart' | 'resolveend' | 'routeconfigloadstart' | 'routeconfigloadend' | 'childactivationstart' | 'childactivationend' | 'activationstart' | 'activationend' | 'scroll';
+/**
+ * Event-driven listener for [Angular Router](https://angular.dev/guide/routing) events.
+ *
+ * @param event - Router event name in lowercase (e.g., 'navigationstart') or array of event names
+ * @param handler - Type-safe handler function for the specific event(s)
+ * @param options - Optional configuration
+ * @returns RouterListenerRef with destroy method for manual unsubscribe
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (isLoading()) {
+ *       <p>Navigation in progress...</p>
+ *     }
+ *   `
+ * })
+ * class NavigationComponent {
+ *   readonly isLoading = signal(false);
+ *
+ *   constructor() {
+ *     routerListener('navigationstart', event => {
+ *       this.isLoading.set(true);
+ *     });
+ *
+ *     routerListener('navigationend', event => {
+ *       this.isLoading.set(false);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare function routerListener(event: 'navigationstart', handler: (event: NavigationStart) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'navigationend', handler: (event: NavigationEnd) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'navigationcancel', handler: (event: NavigationCancel) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'navigationerror', handler: (event: NavigationError) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'navigationskipped', handler: (event: NavigationSkipped) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'routesrecognized', handler: (event: RoutesRecognized) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'guardscheckstart', handler: (event: GuardsCheckStart) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'guardscheckend', handler: (event: GuardsCheckEnd) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'resolvestart', handler: (event: ResolveStart) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'resolveend', handler: (event: ResolveEnd) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'routeconfigloadstart', handler: (event: RouteConfigLoadStart) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'routeconfigloadend', handler: (event: RouteConfigLoadEnd) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'childactivationstart', handler: (event: ChildActivationStart) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'childactivationend', handler: (event: ChildActivationEnd) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'activationstart', handler: (event: ActivationStart) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'activationend', handler: (event: ActivationEnd) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener(event: 'scroll', handler: (event: Scroll) => void, options?: RouterListenerOptions): RouterListenerRef;
+export declare function routerListener<T extends readonly [RouterEventType, ...RouterEventType[]]>(events: T, handler: (event: RouterEventTypeArrayToUnion<T>) => void, options?: RouterListenerOptions): RouterListenerRef;
+type RouterEventTypeMap = {
+    navigationstart: NavigationStart;
+    navigationend: NavigationEnd;
+    navigationcancel: NavigationCancel;
+    navigationerror: NavigationError;
+    navigationskipped: NavigationSkipped;
+    routesrecognized: RoutesRecognized;
+    guardscheckstart: GuardsCheckStart;
+    guardscheckend: GuardsCheckEnd;
+    resolvestart: ResolveStart;
+    resolveend: ResolveEnd;
+    routeconfigloadstart: RouteConfigLoadStart;
+    routeconfigloadend: RouteConfigLoadEnd;
+    childactivationstart: ChildActivationStart;
+    childactivationend: ChildActivationEnd;
+    activationstart: ActivationStart;
+    activationend: ActivationEnd;
+    scroll: Scroll;
+};
+type RouterEventTypeToEventType<T extends RouterEventType> = RouterEventTypeMap[T];
+type RouterEventTypeArrayToUnion<T extends readonly RouterEventType[]> = T[number] extends infer U ? U extends RouterEventType ? RouterEventTypeToEventType<U> : never : never;
+export {};

package/router/title/index.d.ts

@@ -0,0 +1,29 @@
+import { type CreateSignalOptions, type WritableSignal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type TitleOptions = CreateSignalOptions<string> & WithInjector;
+/**
+ * Reactive wrapper around the [Angular Router](https://angular.dev/guide/routing) route title.
+ *
+ * @param options - Optional configuration
+ * @returns A writable signal containing the current route title (string)
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div>
+ *       <h1>{{ pageTitle() }}</h1>
+ *       <button (click)="updateTitle()">Update Title</button>
+ *     </div>
+ *   `
+ * })
+ * class PageComponent {
+ *   readonly pageTitle = title();
+ *
+ *   updateTitle() {
+ *     this.pageTitle.set('New Page Title');
+ *   }
+ * }
+ * ```
+ */
+export declare function title(options?: TitleOptions): WritableSignal<string>;

package/router/url/index.d.ts

@@ -0,0 +1,32 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface UrlOptions extends CreateSignalOptions<string>, WithInjector {
+    /**
+     * Include origin (protocol + host) for absolute URL.
+     * @default false
+     */
+    readonly absolute?: boolean;
+}
+/**
+ * Reactive wrapper around the [Angular Router](https://angular.dev/guide/routing) current URL.
+ *
+ * @param options - Optional configuration
+ * @returns A signal containing the current URL
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div>
+ *       <p>Current URL: {{ currentUrl() }}</p>
+ *       <p>Absolute URL: {{ absoluteUrl() }}</p>
+ *     </div>
+ *   `
+ * })
+ * class UrlComponent {
+ *   readonly currentUrl = url();
+ *   readonly absoluteUrl = url({ absolute: true });
+ * }
+ * ```
+ */
+export declare function url(options?: UrlOptions): Signal<string>;

package/scheduling/debounce-callback/index.d.ts

@@ -0,0 +1,28 @@
+import type { MaybeSignal, WithInjector } from '@signality/core/types';
+/**
+ * Creates a debounced version of a callback function.
+ * The callback will only be executed after the specified wait time has elapsed since the last invocation.
+ *
+ * @param callback - The function to debounce
+ * @param wait - Debounce delay in milliseconds (can be a reactive signal)
+ * @param options - Optional configuration including injector
+ * @returns A debounced version of the callback function
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <input (input)="handleInput($event.target.value)" />
+ *   `,
+ * })
+ * export class SearchComponent {
+ *   readonly debounceTime = input(300);
+ *   readonly searchChange = output<string>();
+ *
+ *   readonly handleInput = debounceCallback(value => {
+ *     this.searchChange.emit(value);
+ *   }, this.debounceTime);
+ * }
+ * ```
+ */
+export declare function debounceCallback<T extends (...args: any[]) => any>(callback: T, wait: MaybeSignal<number>, options?: WithInjector): T;

package/scheduling/index.d.ts

@@ -0,0 +1,3 @@
+export * from '@signality/core/scheduling/debounce-callback';
+export * from '@signality/core/scheduling/interval';
+export * from '@signality/core/scheduling/throttle-callback';

package/scheduling/interval/index.d.ts

@@ -0,0 +1,51 @@
+import { type Signal } from '@angular/core';
+import type { MaybeSignal, WithInjector } from '@signality/core/types';
+export interface IntervalOptions extends WithInjector {
+    /**
+     * Whether to start the interval immediately.
+     * @default false
+     */
+    readonly immediate?: boolean;
+}
+export interface IntervalRef {
+    /** Whether the interval is currently active */
+    readonly isActive: Signal<boolean>;
+    /** Number of times the callback has been executed */
+    readonly counter: Signal<number>;
+    /** Pause the interval */
+    readonly pause: () => void;
+    /** Resume the interval */
+    readonly resume: () => void;
+    /** Reset the counter to 0 */
+    readonly reset: () => void;
+}
+/**
+ * Creates a reactive interval that executes a callback function at specified intervals.
+ * Automatically handles cleanup and supports reactive interval duration.
+ *
+ * @param callback - Function to execute on each interval tick, receives current counter value
+ * @param intervalMs - Interval duration in milliseconds (can be a reactive signal)
+ * @param options - Optional configuration including immediate start and injector
+ * @returns An IntervalRef with control methods and state signals
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <p>Status: {{ polling.isActive() ? 'Polling' : 'Stopped' }}</p>
+ *     <button (click)="polling.pause()">Stop</button>
+ *     <button (click)="polling.resume()">Start</button>
+ *   `,
+ * })
+ * export class PeriodicTask {
+ *   readonly polling = interval(async () => {
+ *     await this.checkStatus();
+ *   }, 5000);
+ *
+ *   async checkStatus() {
+ *     // async operation
+ *   }
+ * }
+ * ```
+ */
+export declare function interval(callback: (counter: number) => void, intervalMs: MaybeSignal<number>, options?: IntervalOptions): IntervalRef;

package/scheduling/throttle-callback/index.d.ts

@@ -0,0 +1,30 @@
+import type { MaybeSignal, WithInjector } from '@signality/core/types';
+/**
+ * Creates a throttled version of a callback function.
+ * The callback will be executed at most once per specified wait interval.
+ *
+ * @param callback - The function to throttle
+ * @param wait - Throttle interval in milliseconds (can be a reactive signal)
+ * @param options - Optional configuration including injector
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div (scroll)="handleScroll($event)">
+ *       Scrollable content
+ *     </div>
+ *   `,
+ * })
+ * export class ScrollComponent {
+ *   readonly throttleTime = input(300);
+ *   readonly scrollChange = output<Event>();
+ *
+ *   readonly handleScroll = throttleCallback(e => {
+ *     this.scrollChange.emit(e);
+ *   }, this.throttleTime);
+ * }
+ * ```
+ */
+export declare function throttleCallback<T extends (...args: any[]) => any>(callback: T, wait: MaybeSignal<number>, options?: WithInjector): T;

package/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './maybe-element-signal';
+export * from './maybe-signal';
+export * from './signal-value';
+export * from './signal-values';
+export * from './unref-element';
+export * from './with-injector';

package/types/maybe-element-signal.d.ts

@@ -0,0 +1,2 @@
+import type { ElementRef, Signal } from '@angular/core';
+export type MaybeElementSignal<T extends Element> = T | ElementRef<T> | Signal<T | ElementRef<T> | null | undefined>;

package/types/maybe-signal.d.ts

@@ -0,0 +1,2 @@
+import type { Signal } from '@angular/core';
+export type MaybeSignal<T> = T | Signal<T>;

package/types/signal-value.d.ts

@@ -0,0 +1,2 @@
+import type { Signal } from '@angular/core';
+export type SignalValue<S> = S extends Signal<infer V> ? V : never;

package/types/signal-values.d.ts

@@ -0,0 +1,5 @@
+import type { Signal } from '@angular/core';
+import type { SignalValue } from './signal-value';
+export type SignalValues<T extends readonly Signal<any>[]> = {
+    readonly [K in keyof T]: SignalValue<T[K]>;
+};

package/types/unref-element.d.ts

@@ -0,0 +1,2 @@
+import type { ElementRef } from '@angular/core';
+export type UnrefElement<T> = T extends ElementRef<infer E> ? E : T;

package/types/with-injector.d.ts

@@ -0,0 +1,8 @@
+import type { Injector } from '@angular/core';
+/**
+ * Provides optional injector property.
+ * Use `Required<WithInjector>` when the injector is required.
+ */
+export interface WithInjector {
+    readonly injector?: Injector;
+}