@tstdl/base 0.93.182 → 0.93.184

package/document-management/service-models/document.service-model.d.ts

@@ -235,8 +235,8 @@ export declare const addOrArchiveDocumentToOrFromCollectionParametersSchema: imp
     }> | undefined;
 }>;
 export declare const proceedDocumentWorkflowParametersSchema: import("../../schema/index.js").ObjectSchema<{
-    id: string;
     state: "error" | "pending" | "running" | "completed" | "review" | "failed";
+    id: string;
 }>;
 export type MetadataParameter = SchemaOutput<typeof metadataParameterObjectSchema>;
 export type LoadDataParameters = SchemaOutput<typeof getDataParametersSchema>;

package/examples/config.d.ts

@@ -0,0 +1,25 @@
+export declare const examplesConfig: {
+    database: {
+        host: string;
+        port: number;
+        user: string;
+        pass: string;
+        database: string;
+        schema: string;
+    };
+    ai: {
+        apiKey: string | undefined;
+        keyFile: string | undefined;
+        vertex: {
+            project: string;
+            location: string;
+        };
+    };
+    s3: {
+        endpoint: string;
+        accessKey: string;
+        secretKey: string;
+        bucket: string | undefined;
+        bucketPerModule: boolean;
+    };
+};

package/examples/config.js

@@ -0,0 +1,26 @@
+import { boolean, positiveInteger, string } from '../utils/config-parser.js';
+export const examplesConfig = {
+    database: {
+        host: string('DATABASE_HOST', '127.0.0.1'),
+        port: positiveInteger('DATABASE_PORT', 15433),
+        user: string('DATABASE_USER', 'tstdl'),
+        pass: string('DATABASE_PASS', 'wf7rq6glrk5jykne'),
+        database: string('DATABASE_NAME', 'tstdl'),
+        schema: string('DATABASE_SCHEMA', 'tstdl'),
+    },
+    ai: {
+        apiKey: string('AI_API_KEY', undefined),
+        keyFile: string('AI_API_KEY_FILE', undefined),
+        vertex: {
+            project: string('AI_VERTEX_PROJECT', 'tstdl-dev'),
+            location: string('AI_VERTEX_LOCATION', 'tstdl-dev'),
+        },
+    },
+    s3: {
+        endpoint: string('S3_ENDPOINT', 'http://localhost:19552'),
+        accessKey: string('S3_ACCESS_KEY', 'tstdl-dev'),
+        secretKey: string('S3_SECRET_KEY', 'tstdl-dev'),
+        bucket: string('S3_BUCKET', undefined),
+        bucketPerModule: boolean('S3_BUCKET_PER_MODULE', true),
+    },
+};

package/notification/server/module.d.ts

@@ -13,7 +13,7 @@ export declare class NotificationConfiguration {
     autoArchiveAfter?: number;
     autoMigrate?: boolean;
 }
-export declare function configureNotification({ injector, ...config }: NotificationConfiguration & {
+export declare function configureNotification({ injector, ...config }?: NotificationConfiguration & {
     injector?: Injector;
 }): void;
 /**

package/notification/server/module.js

@@ -13,7 +13,7 @@ export class NotificationConfiguration {
     autoArchiveAfter;
     autoMigrate;
 }
-export function configureNotification({ injector, ...config }) {
+export function configureNotification({ injector, ...config } = {}) {
     const targetInjector = injector ?? Injector;
     targetInjector.register(NotificationConfiguration, { useValue: { autoArchiveAfter: 30 * 24 * 60 * 60 * 1000, ...config } });
     if (isDefined(config.ancillaryService)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.182",
+  "version": "0.93.184",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -20,7 +20,7 @@
     "test:coverage": "f() { vitest run --coverage --coverage.include=\"source/$1/**/*.ts\" source/$1; }; f",
     "tsc:watch": "tsc --watch",
     "tsc-alias:watch": "tsc-alias --watch",
-    "cleanup:dist": "rm -vrf dist/tools/",
+    "cleanup:dist": "rm -vrf dist/tools/ && find dist -type d -name \"tests\" -exec rm -rf {} +",
     "copy:readmes": "cp README.md dist/ && cd source && find . -name \"README.md\" -exec cp --parents {} ../dist/ \\;",
     "generate:migration": "./scripts/manage-orm.sh generate && npm run copy:orm",
     "generate:readmes": "deno run --allow-run=code2prompt --allow-read --allow-write=source --allow-net=generativelanguage.googleapis.com --allow-env=GEMINI_API_KEY generate-readmes.ts",
@@ -153,8 +153,8 @@
     "type-fest": "^5.5"
   },
   "peerDependencies": {
-    "@aws-sdk/client-s3": "^3.1020",
-    "@aws-sdk/s3-request-presigner": "^3.1020",
+    "@aws-sdk/client-s3": "^3.1021",
+    "@aws-sdk/s3-request-presigner": "^3.1021",
     "@genkit-ai/google-genai": "^1.31",
     "@google-cloud/storage": "^7.19",
     "@toon-format/toon": "^2.1.0",
@@ -170,7 +170,7 @@
     "mjml": "^4.18",
     "nodemailer": "^8.0",
     "pg": "^8.20",
-    "playwright": "^1.58",
+    "playwright": "^1.59",
     "preact": "^10.29",
     "preact-render-to-string": "^6.6",
     "sharp": "^0.34",

package/signals/api.d.ts

@@ -1,12 +1,14 @@
 import type { Tagged } from 'type-fest';
 import type * as Types from './implementation/index.js';
-export type { CreateComputedOptions, CreateEffectOptions, CreateSignalOptions, EffectCleanupRegisterFn, EffectRef, Signal, ToObservableOptions, ToSignalOptions, WritableSignal } from './implementation/index.js';
+export type { CreateComputedOptions, CreateEffectOptions, CreateSignalOptions, EffectCleanupRegisterFn, EffectRef, Signal, ToObservableOptions, ToSignalOptions, ValueEqualityFn, WritableSignal } from './implementation/index.js';
 export type SignalsInjector = Tagged<symbol, 'injector'>;
 export type SignalsConfiguration<TInjector = SignalsInjector> = {
     signal: typeof Types.signal;
     computed: typeof Types.computed;
     effect: typeof Types.effect;
+    linkedSignal: typeof Types.linkedSignal;
     untracked: typeof Types.untracked;
+    resource: typeof Types.resource;
     isSignal: typeof Types.isSignal;
     toSignal: typeof Types.toSignal;
     toObservable: typeof Types.toObservable;
@@ -17,6 +19,8 @@ export type SignalsConfiguration<TInjector = SignalsInjector> = {
 export declare let signal: typeof Types.signal;
 export declare let computed: typeof Types.computed;
 export declare let effect: typeof Types.effect;
+export declare let linkedSignal: typeof Types.linkedSignal;
+export declare let resource: typeof Types.resource;
 export declare let untracked: typeof Types.untracked;
 export declare let isSignal: typeof Types.isSignal;
 export declare let toSignal: typeof Types.toSignal;

package/signals/api.js

@@ -2,6 +2,8 @@
 export let signal = throwSignalsNotConfigured;
 export let computed = throwSignalsNotConfigured;
 export let effect = throwSignalsNotConfigured;
+export let linkedSignal = throwSignalsNotConfigured;
+export let resource = throwSignalsNotConfigured;
 export let untracked = throwSignalsNotConfigured;
 export let isSignal = throwSignalsNotConfigured;
 export let toSignal = throwSignalsNotConfigured;
@@ -11,7 +13,7 @@ export let getCurrentSignalsInjector = throwSignalsNotConfigured;
 export let runInSignalsInjectionContext = throwSignalsNotConfigured;
 /* eslint-enable import/no-mutable-exports */
 export function configureSignals(configuration) {
-    ({ signal, computed, effect, untracked, isSignal, toSignal, toObservable, isInSignalsInjectionContext, runInSignalsInjectionContext, getCurrentSignalsInjector } = configuration);
+    ({ signal, computed, effect, linkedSignal, resource, untracked, isSignal, toSignal, toObservable, isInSignalsInjectionContext, runInSignalsInjectionContext, getCurrentSignalsInjector } = configuration);
 }
 function throwSignalsNotConfigured() {
     throw new Error('Signals are not configured. Use configureDefaultSignalsImplementation() for default implementation or configureSignals() for custom implementation.');

package/signals/implementation/api.d.ts

@@ -3,9 +3,10 @@
  * Copyright Google LLC All Rights Reserved.
  *
  * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
+ * found in the LICENSE file at https://angular.dev/license
  */
 import { SIGNAL } from '../symbol.js';
+import type { WritableSignal } from './signal.js';
 /**
  * A reactive value which notifies consumers of any changes.
  *
@@ -22,3 +23,11 @@ export interface Signal<T> {
  * Checks if the given `value` is a reactive `Signal`.
  */
 export declare function isSignal(value: unknown): value is Signal<unknown>;
+/**
+ * A comparison function which can determine if two values are equal.
+ */
+export type ValueEqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * Checks if the given `value` is a writeable signal.
+ */
+export declare function isWritableSignal(value: unknown): value is WritableSignal<unknown>;

package/signals/implementation/api.js

@@ -3,7 +3,7 @@
  * Copyright Google LLC All Rights Reserved.
  *
  * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
+ * found in the LICENSE file at https://angular.dev/license
  */
 import { SIGNAL } from '../symbol.js';
 /**
@@ -12,3 +12,9 @@ import { SIGNAL } from '../symbol.js';
 export function isSignal(value) {
     return typeof value === 'function' && value[SIGNAL] !== undefined;
 }
+/**
+ * Checks if the given `value` is a writeable signal.
+ */
+export function isWritableSignal(value) {
+    return isSignal(value) && typeof value.set === 'function';
+}

package/signals/implementation/asserts.d.ts

@@ -3,11 +3,11 @@
  * Copyright Google LLC All Rights Reserved.
  *
  * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
+ * found in the LICENSE file at https://angular.dev/license
  */
 /**
  * Asserts that the current stack frame is not within a reactive context. Useful
- * to disallow certain code from running inside a reactive context (see {@link toSignal}).
+ * to disallow certain code from running inside a reactive context (see {@link toSignal})
  *
  * @param debugFn a reference to the function making the assertion (used for the error message).
  */

package/signals/implementation/asserts.js

@@ -3,12 +3,12 @@
  * Copyright Google LLC All Rights Reserved.
  *
  * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
+ * found in the LICENSE file at https://angular.dev/license
  */
-import { getActiveConsumer } from './graph.js';
+import { getActiveConsumer } from './primitive/graph.js';
 /**
  * Asserts that the current stack frame is not within a reactive context. Useful
- * to disallow certain code from running inside a reactive context (see {@link toSignal}).
+ * to disallow certain code from running inside a reactive context (see {@link toSignal})
  *
  * @param debugFn a reference to the function making the assertion (used for the error message).
  */

package/signals/implementation/computed.d.ts

@@ -3,41 +3,9 @@
  * Copyright Google LLC All Rights Reserved.
  *
  * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
+ * found in the LICENSE file at https://angular.dev/license
  */
-import type { Signal } from './api.js';
-import type { ValueEqualityFn } from './equality.js';
-import type { ReactiveNode } from './graph.js';
-import { SIGNAL } from './graph.js';
-/**
- * A computation, which derives a value from a declarative reactive expression.
- *
- * `Computed`s are both producers and consumers of reactivity.
- */
-export interface ComputedNode<T> extends ReactiveNode {
-    /**
-     * Current value of the computation, or one of the sentinel values above (`UNSET`, `COMPUTING`,
-     * `ERROR`).
-     */
-    value: T;
-    /**
-     * If `value` is `ERRORED`, the error caught from the last computation attempt which will
-     * be re-thrown.
-     */
-    error: unknown;
-    /**
-     * The computation function which will produce a new value.
-     */
-    computation: () => T;
-    equal: ValueEqualityFn<T>;
-}
-export type ComputedGetter<T> = (() => T) & {
-    [SIGNAL]: ComputedNode<T>;
-};
-/**
- * Create a computed signal which derives a reactive value from an expression.
- */
-export declare function createComputed<T>(computation: () => T): ComputedGetter<T>;
+import type { Signal, ValueEqualityFn } from './api.js';
 /**
  * Options passed to the `computed` creation function.
  */
@@ -46,8 +14,13 @@ export interface CreateComputedOptions<T> {
      * A comparison function which defines equality for computed values.
      */
     equal?: ValueEqualityFn<T>;
+    /**
+     * A debug name for the computed signal. Used in Angular DevTools to identify the signal.
+     */
+    debugName?: string;
 }
 /**
  * Create a computed `Signal` which derives a reactive value from an expression.
+ * @see [Computed signals](guide/signals#computed-signals)
  */
 export declare function computed<T>(computation: () => T, options?: CreateComputedOptions<T>): Signal<T>;

package/signals/implementation/computed.js

@@ -1,92 +1,23 @@
-/* eslint-disable */
-import { defaultEquals } from './equality.js';
-import { consumerAfterComputation, consumerBeforeComputation, producerAccessed, producerUpdateValueVersion, REACTIVE_NODE, SIGNAL } from './graph.js';
 /**
- * Create a computed signal which derives a reactive value from an expression.
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
  */
-export function createComputed(computation) {
-    const node = Object.create(COMPUTED_NODE);
-    node.computation = computation;
-    const computed = () => {
-        // Check if the value needs updating before returning it.
-        producerUpdateValueVersion(node);
-        // Record that someone looked at this signal.
-        producerAccessed(node);
-        if (node.value === ERRORED) {
-            throw node.error;
-        }
-        return node.value;
-    };
-    computed[SIGNAL] = node;
-    return computed;
-}
-/**
- * A dedicated symbol used before a computed value has been calculated for the first time.
- * Explicitly typed as `any` so we can use it as signal's value.
- */
-const UNSET = /* @__PURE__ */ Symbol('UNSET');
-/**
- * A dedicated symbol used in place of a computed signal value to indicate that a given computation
- * is in progress. Used to detect cycles in computation chains.
- * Explicitly typed as `any` so we can use it as signal's value.
- */
-const COMPUTING = /* @__PURE__ */ Symbol('COMPUTING');
-/**
- * A dedicated symbol used in place of a computed signal value to indicate that a given computation
- * failed. The thrown error is cached until the computation gets dirty again.
- * Explicitly typed as `any` so we can use it as signal's value.
- */
-const ERRORED = /* @__PURE__ */ Symbol('ERRORED');
-const COMPUTED_NODE = {
-    ...REACTIVE_NODE,
-    value: UNSET,
-    dirty: true,
-    error: null,
-    equal: defaultEquals,
-    producerMustRecompute(node) {
-        // Force a recomputation if there's no current value, or if the current value is in the
-        // process of being calculated (which should throw an error).
-        return node.value === UNSET || node.value === COMPUTING;
-    },
-    producerRecomputeValue(node) {
-        if (node.value === COMPUTING) {
-            // Our computation somehow led to a cyclic read of itself.
-            throw new Error('Detected cycle in computations.');
-        }
-        const oldValue = node.value;
-        node.value = COMPUTING;
-        const prevConsumer = consumerBeforeComputation(node);
-        let newValue;
-        try {
-            newValue = node.computation();
-        }
-        catch (err) {
-            newValue = ERRORED;
-            node.error = err;
-        }
-        finally {
-            consumerAfterComputation(node, prevConsumer);
-        }
-        if (oldValue !== UNSET &&
-            oldValue !== ERRORED &&
-            newValue !== ERRORED &&
-            node.equal(oldValue, newValue)) {
-            // No change to `valueVersion` - old and new values are
-            // semantically equivalent.
-            node.value = oldValue;
-            return;
-        }
-        node.value = newValue;
-        node.version++;
-    },
-};
+import { isDevMode } from '../../core.js';
+import { SIGNAL } from '../symbol.js';
+import { createComputed } from './primitive/computed.js';
 /**
  * Create a computed `Signal` which derives a reactive value from an expression.
+ * @see [Computed signals](guide/signals#computed-signals)
  */
 export function computed(computation, options) {
-    const getter = createComputed(computation);
-    if (options?.equal) {
-        getter[SIGNAL].equal = options.equal;
+    const getter = createComputed(computation, options?.equal);
+    if (isDevMode()) {
+        const debugName = options?.debugName;
+        getter[SIGNAL].debugName = debugName;
+        getter.toString = () => `[Computed${debugName ? ' (' + debugName + ')' : ''}: ${getter()}]`;
     }
     return getter;
 }

package/signals/implementation/configure.js

@@ -2,10 +2,12 @@ import { configureSignals } from '../api.js';
 import { isSignal } from './api.js';
 import { computed } from './computed.js';
 import { effect } from './effect.js';
+import { linkedSignal } from './linked_signal.js';
+import { resource } from './resource/resource.js';
+import { signal } from './signal.js';
 import { toObservable } from './to-observable.js';
 import { toSignal } from './to-signal.js';
 import { untracked } from './untracked.js';
-import { signal } from './writable-signal.js';
 /**
  * registers default signals implementation in container
  */
@@ -15,11 +17,13 @@ export function configureDefaultSignalsImplementation() {
         computed,
         effect,
         untracked,
+        linkedSignal,
+        resource,
         isSignal,
         toSignal,
         toObservable,
         isInSignalsInjectionContext: () => true,
         getCurrentSignalsInjector: () => null,
-        runInSignalsInjectionContext: (_, fn) => fn()
+        runInSignalsInjectionContext: (_, fn) => fn(),
     });
 }

package/signals/implementation/effect.d.ts

@@ -1,45 +1,8 @@
-/**
- * @license
- * Copyright Google LLC All Rights Reserved.
- *
- * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
- */
+/** biome-ignore-all lint: <explanation> */
 import type { SignalsInjector } from '../api.js';
-/**
- * An effect can, optionally, register a cleanup function. If registered, the cleanup is executed
- * before the next effect run. The cleanup function makes it possible to "cancel" any work that the
- * previous effect run might have started.
- */
-export type EffectCleanupFn = () => void;
-/**
- * A callback passed to the effect function that makes it possible to register cleanup logic.
- */
-export type EffectCleanupRegisterFn = (cleanupFn: EffectCleanupFn) => void;
-export interface SchedulableEffect {
-    run(): void;
-}
-/**
- * A scheduler which manages the execution of effects.
- */
-export declare abstract class EffectScheduler {
-    /**
-     * Schedule the given effect to be executed at a later time.
-     *
-     * It is an error to attempt to execute any effects synchronously during a scheduling operation.
-     */
-    abstract scheduleEffect(e: SchedulableEffect): void;
-    /**
-     * Run any scheduled effects.
-     */
-    abstract flush(): void;
-}
-export declare class TstdlEffectScheduler implements EffectScheduler {
-    private readonly queue;
-    private hasPendingFlush;
-    scheduleEffect(effect: SchedulableEffect): void;
-    flush(): void;
-}
+import { SIGNAL } from '../symbol.js';
+import { type BaseEffectNode } from './primitive/effect.js';
+import { type EffectScheduler, type SchedulableEffect } from './root_effect_scheduler.js';
 /**
  * A global reactive effect, which can be manually destroyed.
  */
@@ -49,8 +12,15 @@ export interface EffectRef {
      */
     destroy(): void;
 }
+export declare class EffectRefImpl implements EffectRef {
+    [SIGNAL]: EffectNode;
+    constructor(node: EffectNode);
+    destroy(): void;
+}
 /**
  * Options passed to the `effect` function.
+ *
+ * @publicApi 20.0
  */
 export interface CreateEffectOptions {
     /**
@@ -65,17 +35,66 @@ export interface CreateEffectOptions {
      *
      * If this is `false` (the default) the effect will automatically register itself to be cleaned up
      * with the current `DestroyRef`.
+     *
+     * If this is `true` and you want to use the effect outside an injection context, you still
+     * need to provide an `Injector` to the effect.
      */
     manualCleanup?: boolean;
     /**
-     * Whether the `effect` should allow writing to signals.
-     *
-     * Using effects to synchronize data by writing to signals can lead to confusing and potentially
-     * incorrect behavior, and should be enabled only when necessary.
+     * @deprecated no longer required, signal writes are allowed by default.
      */
     allowSignalWrites?: boolean;
+    /**
+     * A debug name for the effect. Used in Angular DevTools to identify the effect.
+     */
+    debugName?: string;
 }
 /**
- * Create a global `Effect` for the given reactive function.
+ * An effect can, optionally, register a cleanup function. If registered, the cleanup is executed
+ * before the next effect run. The cleanup function makes it possible to "cancel" any work that the
+ * previous effect run might have started.
+ *
+ * @see [Effect cleanup functions](guide/signals#effect-cleanup-functions)
+ *
+ * @publicApi 20.0
+ */
+export type EffectCleanupFn = () => void;
+/**
+ * A callback passed to the effect function that makes it possible to register cleanup logic.
+ *
+ * @see [Effect cleanup functions](guide/signals#effect-cleanup-functions)
+ *
+ * @publicApi 20.0
+ */
+export type EffectCleanupRegisterFn = (cleanupFn: EffectCleanupFn) => void;
+/**
+ * Registers an "effect" that will be scheduled & executed whenever the signals that it reads
+ * changes.
+ *
+ * Angular has two different kinds of effect: component effects and root effects. Component effects
+ * are created when `effect()` is called from a component, directive, or within a service of a
+ * component/directive. Root effects are created when `effect()` is called from outside the
+ * component tree, such as in a root service.
+ *
+ * The two effect types differ in their timing. Component effects run as a component lifecycle
+ * event during Angular's synchronization (change detection) process, and can safely read input
+ * signals or create/destroy views that depend on component state. Root effects run as microtasks
+ * and have no connection to the component tree or change detection.
+ *
+ * `effect()` must be run in injection context, unless the `injector` option is manually specified.
+ *
+ * @see [Effects](guide/signals#effects)
+ *
+ * @publicApi 20.0
  */
 export declare function effect(effectFn: (onCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions): EffectRef;
+export interface EffectNode extends BaseEffectNode, SchedulableEffect {
+    cleanupFns: EffectCleanupFn[] | undefined;
+    onDestroyFns: (() => void)[] | null;
+}
+export interface RootEffectNode extends EffectNode {
+    scheduler: EffectScheduler;
+}
+export declare const EFFECT_NODE: Omit<EffectNode, 'fn' | 'destroy' | 'injector' | 'notifier'>;
+export declare const ROOT_EFFECT_NODE: Omit<RootEffectNode, 'fn' | 'scheduler' | 'notifier' | 'injector'>;
+export declare function createRootEffect(fn: (onCleanup: EffectCleanupRegisterFn) => void, scheduler: EffectScheduler): RootEffectNode;