@sdcorejs/angular 19.1.3 → 19.1.4

package/services/persistence/src/graph-serializer.d.ts

@@ -0,0 +1,16 @@
+import { SdGraphSerializerLimits, SdPersistenceErrorCode, SdPersistenceSerializer } from './persistence.model';
+export declare const SD_GRAPH_HARD_LIMITS: Readonly<SdGraphSerializerLimits>;
+export declare class SdPersistenceError extends Error {
+    readonly code: SdPersistenceErrorCode;
+    readonly name = "SdPersistenceError";
+    constructor(code: SdPersistenceErrorCode, message: string);
+}
+export declare class SdGraphSerializer implements SdPersistenceSerializer {
+    #private;
+    readonly format = "sdcorejs.graph@1";
+    readonly limits: Readonly<SdGraphSerializerLimits>;
+    constructor(limits?: Partial<SdGraphSerializerLimits>);
+    stringify<T>(value: T): string;
+    parse<T = unknown>(serialized: string): T;
+    clone<T>(value: T): T;
+}

package/services/persistence/src/persistence-envelope.d.ts

@@ -0,0 +1,28 @@
+export declare const SD_PERSISTENCE_ENVELOPE_FORMAT = "sdcorejs.persistence-envelope";
+export declare const SD_PERSISTENCE_ENVELOPE_VERSION = 1;
+export interface SdPersistenceEnvelopeLimits {
+    maxDocumentCharacters: number;
+    maxPayloadCharacters: number;
+    maxSerializerCharacters: number;
+    maxIdentityCharacters: number;
+}
+export declare const SD_PERSISTENCE_ENVELOPE_HARD_LIMITS: Readonly<SdPersistenceEnvelopeLimits>;
+export interface SdPersistenceValueEnvelope {
+    format: typeof SD_PERSISTENCE_ENVELOPE_FORMAT;
+    version: typeof SD_PERSISTENCE_ENVELOPE_VERSION;
+    kind: 'value';
+    identity: string;
+    serializer: string;
+    payload: string;
+}
+export interface SdPersistenceTombstoneEnvelope {
+    format: typeof SD_PERSISTENCE_ENVELOPE_FORMAT;
+    version: typeof SD_PERSISTENCE_ENVELOPE_VERSION;
+    kind: 'tombstone';
+    identity: string;
+    serializer: string;
+}
+export type SdPersistenceEnvelope = SdPersistenceValueEnvelope | SdPersistenceTombstoneEnvelope;
+export declare function stringifySdPersistenceValueEnvelope(identity: string, serializer: string, payload: string, limits?: Partial<SdPersistenceEnvelopeLimits>): string;
+export declare function stringifySdPersistenceTombstoneEnvelope(identity: string, serializer: string, limits?: Partial<SdPersistenceEnvelopeLimits>): string;
+export declare function parseSdPersistenceEnvelope(serialized: string, expectedIdentity: string, expectedSerializer: string, limits?: Partial<SdPersistenceEnvelopeLimits>): SdPersistenceEnvelope | undefined;

package/services/persistence/src/persistence-key.d.ts

@@ -0,0 +1,17 @@
+import { SdPersistenceIdentityCanonicalizer } from './persistence.model';
+export interface SdPersistenceKeyField {
+    tag: string;
+    value: string;
+}
+export declare class SdPersistenceIdentityError extends Error {
+    readonly name = "SdPersistenceIdentityError";
+    constructor(message: string);
+}
+export declare function buildSdPersistenceKey(baseKey: string, fields: readonly SdPersistenceKeyField[]): string;
+export declare class SdGraphIdentityCanonicalizer implements SdPersistenceIdentityCanonicalizer {
+    #private;
+    readonly format = "sdcorejs.graph-identity@1";
+    canonicalize(value: unknown): string;
+}
+export declare function canonicalizeSdPersistenceValue(canonicalizer: SdPersistenceIdentityCanonicalizer, value: unknown, label: string): string;
+export declare function digestSdPersistenceKey(value: string): string;

package/services/persistence/src/persistence.model.d.ts

@@ -0,0 +1,63 @@
+export declare const SD_GRAPH_FORMAT = "sdcorejs.graph";
+export declare const SD_GRAPH_VERSION = 1;
+export type SdPersistenceErrorCode = 'INVALID_DOCUMENT' | 'UNKNOWN_FORMAT' | 'UNKNOWN_VERSION' | 'INVALID_NODE' | 'INVALID_REFERENCE' | 'UNSUPPORTED_VALUE' | 'LIMIT_EXCEEDED';
+export interface SdGraphSerializerLimits {
+    maxDocumentCharacters: number;
+    maxDepth: number;
+    maxNodes: number;
+    maxEntries: number;
+    maxStringCharacters: number;
+    maxKeyCharacters: number;
+    maxBigIntDigits: number;
+}
+export interface SdPersistenceSerializer {
+    readonly format: string;
+    stringify<T>(value: T): string;
+    parse<T = unknown>(serialized: string): T;
+    clone<T>(value: T): T;
+}
+/** Deterministic, versioned canonicalization used only for persistence identity. */
+export interface SdPersistenceIdentityCanonicalizer {
+    readonly format: string;
+    canonicalize(value: unknown): string;
+}
+export type SdGraphSpecialNumber = 'NaN' | 'Infinity' | '-Infinity' | '-0';
+export type SdGraphValue = null | boolean | string | number | {
+    $ref: number;
+} | {
+    $type: 'undefined';
+} | {
+    $type: 'number';
+    value: SdGraphSpecialNumber;
+} | {
+    $type: 'bigint';
+    value: string;
+};
+export interface SdGraphArrayNode {
+    type: 'array';
+    values: SdGraphValue[];
+}
+export interface SdGraphObjectNode {
+    type: 'object';
+    prototype: 'object' | 'null';
+    entries: [string, SdGraphValue][];
+}
+export interface SdGraphDateNode {
+    type: 'date';
+    value: string;
+}
+export interface SdGraphMapNode {
+    type: 'map';
+    entries: [SdGraphValue, SdGraphValue][];
+}
+export interface SdGraphSetNode {
+    type: 'set';
+    values: SdGraphValue[];
+}
+export type SdGraphNode = SdGraphArrayNode | SdGraphObjectNode | SdGraphDateNode | SdGraphMapNode | SdGraphSetNode;
+export interface SdGraphEnvelope {
+    format: typeof SD_GRAPH_FORMAT;
+    version: typeof SD_GRAPH_VERSION;
+    root: SdGraphValue;
+    nodes: SdGraphNode[];
+}

package/services/persistence/src/storage-adapter.d.ts

@@ -0,0 +1,29 @@
+import { InjectionToken } from '@angular/core';
+import * as i0 from "@angular/core";
+export type SdPersistenceStorageArea = 'local' | 'session';
+export type SdPersistenceStorageRead = {
+    status: 'found';
+    value: string;
+} | {
+    status: 'absent';
+} | {
+    status: 'unavailable';
+};
+export interface SdPersistenceStorageAdapter {
+    /** Optional tri-state read. Legacy adapters may continue to implement only `getItem`. */
+    readItem?(area: SdPersistenceStorageArea, key: string): SdPersistenceStorageRead;
+    getItem(area: SdPersistenceStorageArea, key: string): string | null;
+    setItem(area: SdPersistenceStorageArea, key: string, value: string): boolean;
+    removeItem(area: SdPersistenceStorageArea, key: string): boolean;
+}
+export declare class SdBrowserStorageAdapter implements SdPersistenceStorageAdapter {
+    #private;
+    readItem(area: SdPersistenceStorageArea, key: string): SdPersistenceStorageRead;
+    getItem(area: SdPersistenceStorageArea, key: string): string | null;
+    setItem(area: SdPersistenceStorageArea, key: string, value: string): boolean;
+    removeItem(area: SdPersistenceStorageArea, key: string): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdBrowserStorageAdapter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SdBrowserStorageAdapter>;
+}
+export declare function readSdPersistenceStorageItem(adapter: SdPersistenceStorageAdapter, area: SdPersistenceStorageArea, key: string): SdPersistenceStorageRead;
+export declare const SD_PERSISTENCE_STORAGE_ADAPTER: InjectionToken<SdPersistenceStorageAdapter>;

package/services/storage/src/storage.model.d.ts

@@ -1,20 +1,35 @@
 import { InjectionToken } from '@angular/core';
+import { SdPersistenceIdentityCanonicalizer, SdPersistenceSerializer } from '@sdcorejs/angular/services/persistence';
 import { BehaviorSubject, Observable } from 'rxjs';
-export interface SdStorageOption<T = any> {
-    type?: 'session';
+export interface SdStorageOption<T = unknown> {
+    type?: 'local' | 'session';
     default?: T;
-    args?: Record<string, any>;
+    args?: Readonly<Record<string, unknown>>;
+    namespace?: string;
+    version?: string | number;
+    serializer?: SdPersistenceSerializer;
+    identityCanonicalizer?: SdPersistenceIdentityCanonicalizer;
 }
-export interface SdStorage<T = any> {
-    get: () => T;
+export interface SdStorage<T = unknown> {
+    get: () => T | undefined;
     set: (data: T) => void;
     setSilent: (data: T) => void;
     has: () => boolean;
     remove: () => void;
+    destroy: () => void;
+    subject: BehaviorSubject<T | undefined>;
+    observer: Observable<T | undefined>;
+}
+export interface SdStorageWithDefault<T> extends Omit<SdStorage<T>, 'get' | 'subject' | 'observer'> {
+    get: () => T;
     subject: BehaviorSubject<T>;
     observer: Observable<T>;
 }
 export interface ISdStorageConfiguration {
     key?: (key: string) => string;
+    namespace?: string;
+    version?: string | number;
+    serializer?: SdPersistenceSerializer;
+    identityCanonicalizer?: SdPersistenceIdentityCanonicalizer;
 }
 export declare const SD_STORAGE_CONFIG: InjectionToken<ISdStorageConfiguration>;

package/services/storage/src/storage.service.d.ts

@@ -1,9 +1,12 @@
-import { SdStorage, SdStorageOption } from './storage.model';
+import { SdStorage, SdStorageOption, SdStorageWithDefault } from './storage.model';
 import * as i0 from "@angular/core";
 export declare class SdStorageService {
     #private;
-    private readonly configuration;
-    create<T = any>(key: string | object, option?: SdStorageOption<T>): SdStorage<T>;
+    constructor();
+    create<T>(key: string | object, option: SdStorageOption<T> & {
+        default: T;
+    }): SdStorageWithDefault<T>;
+    create<T = unknown>(key: string | object, option?: SdStorageOption<unknown>): SdStorage<T>;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdStorageService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<SdStorageService>;
 }

package/services/task/index.d.ts

@@ -0,0 +1,3 @@
+export * from './src/task.model';
+export * from './src/task.tokens';
+export * from './src/task.service';

package/services/task/src/task.model.d.ts

@@ -0,0 +1,75 @@
+import { Signal } from '@angular/core';
+export type SdTaskMaybeAsync<T> = T | PromiseLike<T>;
+export type SdTaskStatus = 'idle' | 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+export type SdTaskConnectionState = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'error';
+export interface SdTaskState<TResult = unknown> {
+    readonly id: string;
+    readonly status: SdTaskStatus;
+    readonly progress?: number;
+    readonly title?: string;
+    readonly message?: string;
+    readonly error?: unknown;
+    readonly result?: TResult;
+    readonly updatedAt?: number | Date;
+}
+export interface SdTaskRetryPolicy {
+    readonly maxAttempts?: number;
+    readonly initialDelayMs?: number;
+    readonly backoff?: number;
+    readonly maxDelayMs?: number;
+    readonly jitter?: number;
+}
+export interface SdTaskLoadContext<TResult = unknown> {
+    readonly id: string;
+    readonly signal: AbortSignal;
+    readonly attempt: number;
+    readonly state: SdTaskState<TResult>;
+}
+export interface SdTaskActionContext<TResult = unknown> {
+    readonly id: string;
+    readonly state: SdTaskState<TResult>;
+}
+export type SdTaskCancelResult<TResult = unknown> = void | boolean | SdTaskState<TResult>;
+export type SdTaskCancelHandler<TResult = unknown> = (context: SdTaskActionContext<TResult>) => SdTaskMaybeAsync<SdTaskCancelResult<TResult>>;
+interface SdTaskSourceBase<TResult> {
+    readonly cancel?: SdTaskCancelHandler<TResult>;
+}
+export interface SdTaskManualSource<TResult = unknown> extends SdTaskSourceBase<TResult> {
+    readonly mode: 'manual';
+}
+export interface SdTaskPollingSource<TResult = unknown> extends SdTaskSourceBase<TResult> {
+    readonly mode: 'poll';
+    readonly load: (context: SdTaskLoadContext<TResult>) => SdTaskMaybeAsync<SdTaskState<TResult>>;
+    readonly intervalMs?: number;
+    readonly retry?: SdTaskRetryPolicy;
+}
+export interface SdTaskSseSource<TResult = unknown> extends SdTaskSourceBase<TResult> {
+    readonly mode: 'sse';
+    readonly url: string | (() => string);
+    readonly eventSourceInit?: EventSourceInit;
+    readonly parse?: (event: MessageEvent<string>) => SdTaskMaybeAsync<SdTaskState<TResult>>;
+    readonly retry?: SdTaskRetryPolicy;
+}
+export type SdTaskSource<TResult = unknown> = SdTaskManualSource<TResult> | SdTaskPollingSource<TResult> | SdTaskSseSource<TResult>;
+export interface SdTaskWatchOptions<TResult = unknown> {
+    readonly id: string;
+    readonly initialState?: SdTaskState<TResult>;
+    readonly source: SdTaskSource<TResult>;
+}
+export interface SdTaskView<TResult = unknown> {
+    readonly id: string;
+    readonly state: Signal<SdTaskState<TResult>>;
+    readonly connection: Signal<SdTaskConnectionState>;
+    readonly error: Signal<unknown | null>;
+    readonly subscriberCount: Signal<number>;
+    readonly canCancel: Signal<boolean>;
+    readonly canRetry: Signal<boolean>;
+    cancel(): Promise<boolean>;
+    retry(): void;
+}
+export interface SdTaskSubscription<TResult = unknown> extends SdTaskView<TResult> {
+    readonly destroyed: Signal<boolean>;
+    destroy(): void;
+}
+export declare function isSdTaskTerminal(status: SdTaskStatus): boolean;
+export {};

package/services/task/src/task.service.d.ts

@@ -0,0 +1,14 @@
+import { SdTaskState, SdTaskSubscription, SdTaskView, SdTaskWatchOptions } from './task.model';
+import * as i0 from "@angular/core";
+export declare class SdTaskService {
+    #private;
+    readonly tasks: import("@angular/core").Signal<SdTaskView<unknown>[]>;
+    constructor();
+    watch<TResult = unknown>(options: SdTaskWatchOptions<TResult>): SdTaskSubscription<TResult>;
+    get<TResult = unknown>(id: string): SdTaskView<TResult> | undefined;
+    update<TResult = unknown>(id: string, patch: Partial<Omit<SdTaskState<TResult>, 'id'>>): boolean;
+    cancel(id: string): Promise<boolean>;
+    retry(id: string): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdTaskService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SdTaskService>;
+}

package/services/task/src/task.tokens.d.ts

@@ -0,0 +1,12 @@
+import { InjectionToken } from '@angular/core';
+export interface SdTaskEventSource {
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent<string>) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    close(): void;
+}
+export interface SdTaskEventSourceFactory {
+    create(url: string, init?: EventSourceInit): SdTaskEventSource;
+}
+export declare const SD_TASK_EVENT_SOURCE_FACTORY: InjectionToken<SdTaskEventSourceFactory | null>;
+export declare const SD_TASK_RANDOM: InjectionToken<() => number>;

package/services/unsaved-changes/index.d.ts

@@ -0,0 +1,4 @@
+export * from './src/unsaved-changes.model';
+export * from './src/unsaved-changes.tokens';
+export * from './src/unsaved-changes.service';
+export * from './src/unsaved-changes.adapters';

package/services/unsaved-changes/src/unsaved-changes.adapters.d.ts

@@ -0,0 +1,15 @@
+import { FormGroup } from '@angular/forms';
+import { CanDeactivateFn } from '@angular/router';
+import { SdUnsavedChangesConfirmOptions, SdUnsavedChangesMaybeAsync, SdUnsavedChangesRegistration } from './unsaved-changes.model';
+import { SdUnsavedChangesService } from './unsaved-changes.service';
+export interface SdUnsavedChangesFormOptions<TValue> {
+    readonly id: string;
+    readonly scope?: unknown;
+    readonly message?: string;
+    readonly save?: (value: TValue) => SdUnsavedChangesMaybeAsync<void | boolean>;
+    readonly reset?: (form: FormGroup) => SdUnsavedChangesMaybeAsync<void | boolean>;
+    readonly discard?: (form: FormGroup) => SdUnsavedChangesMaybeAsync<void | boolean>;
+}
+export declare function registerSdUnsavedChangesForm<TValue extends Record<string, unknown>>(service: SdUnsavedChangesService, form: FormGroup, options: SdUnsavedChangesFormOptions<TValue>): SdUnsavedChangesRegistration;
+export declare function createSdUnsavedChangesCloseGuard(service: SdUnsavedChangesService, options?: Omit<SdUnsavedChangesConfirmOptions, 'reason'>): () => Promise<boolean>;
+export declare const sdUnsavedChangesGuard: CanDeactivateFn<unknown>;

package/services/unsaved-changes/src/unsaved-changes.model.d.ts

@@ -0,0 +1,41 @@
+import { Signal } from '@angular/core';
+export type SdUnsavedChangesMaybeAsync<T> = T | PromiseLike<T>;
+export type SdUnsavedChangesDirtySource = boolean | Signal<boolean> | (() => boolean);
+export type SdUnsavedChangesDecision = 'save' | 'discard' | 'cancel';
+export type SdUnsavedChangesReason = 'navigation' | 'close' | 'manual';
+export interface SdUnsavedChangesWatcher {
+    readonly id: string;
+    readonly scope?: unknown;
+    readonly isDirty: SdUnsavedChangesDirtySource;
+    readonly message?: string;
+    readonly save?: () => SdUnsavedChangesMaybeAsync<void | boolean>;
+    readonly reset?: () => SdUnsavedChangesMaybeAsync<void | boolean>;
+    readonly discard?: () => SdUnsavedChangesMaybeAsync<void | boolean>;
+    readonly cleanup?: () => void;
+}
+export interface SdUnsavedChangesPromptContext {
+    readonly reason: SdUnsavedChangesReason;
+    readonly scope?: unknown;
+    readonly message: string;
+    readonly watchers: readonly SdUnsavedChangesRegistration[];
+}
+export interface SdUnsavedChangesConfirmationAdapter {
+    confirm(context: SdUnsavedChangesPromptContext): SdUnsavedChangesMaybeAsync<SdUnsavedChangesDecision | boolean>;
+}
+export interface SdUnsavedChangesRegistration {
+    readonly id: string;
+    readonly scope?: unknown;
+    readonly message?: string;
+    readonly destroyed: Signal<boolean>;
+    readonly dirty: Signal<boolean>;
+    markDirty(): void;
+    markPristine(): void;
+    save(): Promise<boolean>;
+    reset(): Promise<boolean>;
+    discard(): Promise<boolean>;
+    destroy(): void;
+}
+export interface SdUnsavedChangesConfirmOptions {
+    readonly scope?: unknown;
+    readonly reason?: SdUnsavedChangesReason;
+}

package/services/unsaved-changes/src/unsaved-changes.service.d.ts

@@ -0,0 +1,16 @@
+import { SdUnsavedChangesConfirmOptions, SdUnsavedChangesRegistration, SdUnsavedChangesWatcher } from './unsaved-changes.model';
+import * as i0 from "@angular/core";
+export declare class SdUnsavedChangesService {
+    #private;
+    readonly registrations: import("@angular/core").Signal<SdUnsavedChangesRegistration[]>;
+    readonly dirty: import("@angular/core").Signal<boolean>;
+    constructor();
+    register(watcher: SdUnsavedChangesWatcher): SdUnsavedChangesRegistration;
+    hasChanges(scope?: unknown): boolean;
+    confirmLeave(options?: SdUnsavedChangesConfirmOptions): Promise<boolean>;
+    saveAll(scope?: unknown): Promise<boolean>;
+    resetAll(scope?: unknown): Promise<boolean>;
+    discardAll(scope?: unknown): Promise<boolean>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdUnsavedChangesService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SdUnsavedChangesService>;
+}

package/services/unsaved-changes/src/unsaved-changes.tokens.d.ts

@@ -0,0 +1,9 @@
+import { InjectionToken } from '@angular/core';
+import { SdUnsavedChangesConfirmationAdapter } from './unsaved-changes.model';
+export interface SdUnsavedChangesWindow {
+    addEventListener(type: 'beforeunload', listener: (event: BeforeUnloadEvent) => void): void;
+    removeEventListener(type: 'beforeunload', listener: (event: BeforeUnloadEvent) => void): void;
+    confirm?(message?: string): boolean;
+}
+export declare const SD_UNSAVED_CHANGES_WINDOW: InjectionToken<SdUnsavedChangesWindow | null>;
+export declare const SD_UNSAVED_CHANGES_CONFIRMATION_ADAPTER: InjectionToken<SdUnsavedChangesConfirmationAdapter>;

package/services/viewport/index.d.ts

@@ -0,0 +1,3 @@
+export * from './src/viewport.model';
+export * from './src/viewport.tokens';
+export * from './src/viewport.service';

package/services/viewport/src/viewport.model.d.ts

@@ -0,0 +1,12 @@
+export interface SdViewportBreakpoints {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+}
+export type SdViewportBreakpoint = keyof SdViewportBreakpoints;
+export interface SdViewport {
+    innerWidth: number;
+    innerHeight?: number;
+    addEventListener(type: 'resize', listener: EventListenerOrEventListenerObject): void;
+    removeEventListener(type: 'resize', listener: EventListenerOrEventListenerObject): void;
+}

package/services/viewport/src/viewport.service.d.ts

@@ -0,0 +1,18 @@
+import * as i0 from "@angular/core";
+/**
+ * Exposes one SSR-safe, signal-based viewport state for the application.
+ * Breakpoints use min-width semantics and can be configured through `SD_VIEWPORT_BREAKPOINTS`.
+ */
+export declare class SdViewportService {
+    #private;
+    readonly breakpoints: Readonly<import("@sdcorejs/angular/services/viewport").SdViewportBreakpoints>;
+    readonly width: import("@angular/core").Signal<number>;
+    readonly height: import("@angular/core").Signal<number>;
+    readonly currentBreakpoint: import("@angular/core").Signal<keyof import("@sdcorejs/angular/services/viewport").SdViewportBreakpoints>;
+    readonly isMobile: import("@angular/core").Signal<boolean>;
+    readonly isTablet: import("@angular/core").Signal<boolean>;
+    readonly isDesktop: import("@angular/core").Signal<boolean>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdViewportService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SdViewportService>;
+}

package/services/viewport/src/viewport.tokens.d.ts

@@ -0,0 +1,6 @@
+import { InjectionToken } from '@angular/core';
+import { SdViewport, SdViewportBreakpoints } from './viewport.model';
+export declare const SD_VIEWPORT_DEFAULT_BREAKPOINTS: Readonly<SdViewportBreakpoints>;
+export declare const SD_VIEWPORT: InjectionToken<SdViewport | null>;
+export declare const SD_VIEWPORT_BREAKPOINTS: InjectionToken<Readonly<SdViewportBreakpoints>>;
+export declare function sdNormalizeViewportBreakpoints(value: Readonly<SdViewportBreakpoints>): Readonly<SdViewportBreakpoints>;