@signaldb/svelte 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/base/core/src/utils/queryDelta.d.ts

@@ -0,0 +1,83 @@
+import type { BaseItem } from '../Collection/types';
+/**
+ * The change between two consecutive results of the same query, expressed so it can be applied to
+ * the earlier result to obtain the later one.
+ *
+ * Indices in `added` and `moved` are positions in the *resulting* array and are always ascending,
+ * which is what makes applying them a matter of splicing in order. Removals and moves name items by
+ * id only: whoever applies the delta still holds the previous result and can look the item up
+ * there, so there is no reason to send it twice — the point of the whole exercise is that a change
+ * costs the size of the change, not the size of the result.
+ */
+export interface QueryDelta<T extends BaseItem = BaseItem> {
+    /** Items that were not in the previous result, at their position in the new one. */
+    added: {
+        index: number;
+        item: T;
+    }[];
+    /** Items that were in the previous result and whose contents changed. */
+    changed: T[];
+    /** Ids of items that are no longer in the result. */
+    removed: any[];
+    /** Items that stayed, at their new position, because the order around them changed. */
+    moved: {
+        index: number;
+        id: any;
+    }[];
+    /** Length of the resulting array — lets a recipient verify it applied the delta to the result it was computed against. */
+    resultCount: number;
+}
+/**
+ * Checks whether a delta leaves the result it is applied to unchanged.
+ * @param delta - The delta to inspect.
+ * @returns `true` when applying the delta would be a no-op.
+ */
+export declare function isEmptyQueryDelta(delta: QueryDelta<any>): boolean;
+/**
+ * Calls a state-change callback, passing the delta only when there is one.
+ *
+ * A callback invoked as `callback(state, undefined)` has been handed two arguments, which is a
+ * different thing from being handed one — visible to anything that inspects arity, and to any test
+ * that asserts on the call.
+ * @template T - The type of the items.
+ * @param callback - The callback to invoke.
+ * @param state - The state to report.
+ * @param delta - The delta to report, if there is one.
+ */
+export declare function callWithDelta<T extends BaseItem>(callback: (state: 'active' | 'complete' | 'error', delta?: QueryDelta<T>) => void, state: 'active' | 'complete' | 'error', delta?: QueryDelta<T>): void;
+/**
+ * Checks whether a delta describes a change to the given result.
+ *
+ * A delta is only meaningful against the exact result it was computed from — it names positions in
+ * an array and items by id alone. Applying one to anything else produces a result that looks
+ * plausible and is wrong, and from then on every further delta compounds the error. This is the
+ * cheap structural check that catches that: every id the delta expects to find is there, every id
+ * it expects to be new is not, and the arithmetic on the length works out. It costs the size of the
+ * delta, not the size of the result.
+ * @template T - The type of the items.
+ * @param previous - The result the delta would be applied to.
+ * @param delta - The delta to check.
+ * @returns `true` when the delta can be applied.
+ */
+export declare function canApplyQueryDelta<T extends BaseItem>(previous: T[], delta: QueryDelta<T>): boolean;
+/**
+ * Computes the delta between two results of the same query.
+ *
+ * A fallback for the cases where the change that produced the new result is not available — a query
+ * that had to be re-executed in full, for instance. It costs a pass over both results, but it is
+ * paid once, on the side that has both of them, instead of shipping the entire new result to
+ * everyone who only needs to know what changed.
+ * @template T - The type of the items.
+ * @param previous - The result the delta should be relative to.
+ * @param next - The result the delta should produce.
+ * @returns The delta between the two results.
+ */
+export declare function diffQueryResults<T extends BaseItem>(previous: T[], next: T[]): QueryDelta<T>;
+/**
+ * Applies a delta to the result it was computed against.
+ * @template T - The type of the items.
+ * @param previous - The result the delta is relative to. Not modified.
+ * @param delta - The delta to apply.
+ * @returns The resulting items.
+ */
+export declare function applyQueryDelta<T extends BaseItem>(previous: T[], delta: QueryDelta<T>): T[];

package/dist/base/core/src/utils/queryDelta.js

@@ -0,0 +1,231 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEmptyQueryDelta = isEmptyQueryDelta;
+exports.callWithDelta = callWithDelta;
+exports.canApplyQueryDelta = canApplyQueryDelta;
+exports.diffQueryResults = diffQueryResults;
+exports.applyQueryDelta = applyQueryDelta;
+const isEqual_1 = __importDefault(require("./isEqual"));
+/**
+ * Checks whether a delta leaves the result it is applied to unchanged.
+ * @param delta - The delta to inspect.
+ * @returns `true` when applying the delta would be a no-op.
+ */
+function isEmptyQueryDelta(delta) {
+    return delta.added.length === 0
+        && delta.changed.length === 0
+        && delta.removed.length === 0
+        && delta.moved.length === 0;
+}
+/**
+ * Calls a state-change callback, passing the delta only when there is one.
+ *
+ * A callback invoked as `callback(state, undefined)` has been handed two arguments, which is a
+ * different thing from being handed one — visible to anything that inspects arity, and to any test
+ * that asserts on the call.
+ * @template T - The type of the items.
+ * @param callback - The callback to invoke.
+ * @param state - The state to report.
+ * @param delta - The delta to report, if there is one.
+ */
+function callWithDelta(callback, state, delta) {
+    if (delta == null) {
+        callback(state);
+        return;
+    }
+    callback(state, delta);
+}
+/**
+ * Checks whether a delta describes a change to the given result.
+ *
+ * A delta is only meaningful against the exact result it was computed from — it names positions in
+ * an array and items by id alone. Applying one to anything else produces a result that looks
+ * plausible and is wrong, and from then on every further delta compounds the error. This is the
+ * cheap structural check that catches that: every id the delta expects to find is there, every id
+ * it expects to be new is not, and the arithmetic on the length works out. It costs the size of the
+ * delta, not the size of the result.
+ * @template T - The type of the items.
+ * @param previous - The result the delta would be applied to.
+ * @param delta - The delta to check.
+ * @returns `true` when the delta can be applied.
+ */
+function canApplyQueryDelta(previous, delta) {
+    const present = new Set(previous.map(item => item.id));
+    const seen = new Set();
+    const claim = (id, shouldExist) => {
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return present.has(id) === shouldExist;
+    };
+    const expectedCount = previous.length - delta.removed.length + delta.added.length;
+    if (expectedCount !== delta.resultCount)
+        return false;
+    if (!delta.removed.every(id => claim(id, true)))
+        return false;
+    if (!delta.added.every(({ index, item }) => claim(item.id, false)
+        && index >= 0 && index < delta.resultCount))
+        return false;
+    if (!delta.changed.every(item => present.has(item.id)))
+        return false;
+    return delta.moved.every(({ index, id }) => present.has(id)
+        && !delta.removed.includes(id)
+        && index >= 0 && index < delta.resultCount);
+}
+/**
+ * Indices of the longest strictly increasing subsequence of the given numbers.
+ * Used to decide which items keep their place when a result is reordered: everything outside the
+ * subsequence has to move, everything inside it is already in the right relative order.
+ * @param sequence - The numbers to inspect.
+ * @returns The indices into `sequence` that form the longest increasing subsequence.
+ */
+function longestIncreasingSubsequence(sequence) {
+    if (sequence.length === 0)
+        return [];
+    // `tails[length - 1]` is the index of the smallest possible tail of an increasing subsequence of
+    // that length; `previous` links each index back to its predecessor so the run can be walked out.
+    const tails = [];
+    const previous = Array.from({ length: sequence.length }).fill(-1);
+    for (let index = 0; index < sequence.length; index += 1) {
+        const value = sequence[index];
+        let low = 0;
+        let high = tails.length;
+        while (low < high) {
+            const middle = (low + high) >> 1;
+            if (sequence[tails[middle]] < value) {
+                low = middle + 1;
+            }
+            else {
+                high = middle;
+            }
+        }
+        if (low > 0)
+            previous[index] = tails[low - 1];
+        tails[low] = index;
+    }
+    const result = [];
+    let cursor = tails.at(-1);
+    while (cursor !== -1) {
+        result.push(cursor);
+        cursor = previous[cursor];
+    }
+    return result.toReversed();
+}
+/**
+ * Computes the delta between two results of the same query.
+ *
+ * A fallback for the cases where the change that produced the new result is not available — a query
+ * that had to be re-executed in full, for instance. It costs a pass over both results, but it is
+ * paid once, on the side that has both of them, instead of shipping the entire new result to
+ * everyone who only needs to know what changed.
+ * @template T - The type of the items.
+ * @param previous - The result the delta should be relative to.
+ * @param next - The result the delta should produce.
+ * @returns The delta between the two results.
+ */
+function diffQueryResults(previous, next) {
+    // Both arrays are walked in full here, so the cheap ways out are worth taking. Two results
+    // holding the same items in the same places are the common case by some margin: this is asked
+    // several times per write, and most of those ask about a query the write did not really change.
+    if (holdsTheSameItems(previous, next)) {
+        return { added: [], changed: [], removed: [], moved: [], resultCount: next.length };
+    }
+    const previousIndexById = new Map();
+    previous.forEach((item, index) => previousIndexById.set(item.id, index));
+    const added = [];
+    const changed = [];
+    // Positions in `previous` of the items that survive, in the order they appear in `next`. An
+    // increasing run in here is a stretch of items whose relative order did not change — and when
+    // the whole thing is increasing, nothing moved and the work below can be skipped entirely.
+    const survivingPreviousIndices = [];
+    const survivingNextIndices = [];
+    const survived = Array.from({ length: previous.length }).fill(false);
+    let orderPreserved = true;
+    let lastPreviousIndex = -1;
+    next.forEach((item, index) => {
+        const previousIndex = previousIndexById.get(item.id);
+        if (previousIndex == null) {
+            added.push({ index, item });
+            return;
+        }
+        survived[previousIndex] = true;
+        if (!(0, isEqual_1.default)(previous[previousIndex], item))
+            changed.push(item);
+        if (previousIndex < lastPreviousIndex)
+            orderPreserved = false;
+        lastPreviousIndex = previousIndex;
+        survivingPreviousIndices.push(previousIndex);
+        survivingNextIndices.push(index);
+    });
+    const removed = [];
+    previous.forEach((item, index) => {
+        if (!survived[index])
+            removed.push(item.id);
+    });
+    const moved = [];
+    if (!orderPreserved) {
+        const stationary = new Set(longestIncreasingSubsequence(survivingPreviousIndices)
+            .map(position => survivingNextIndices[position]));
+        survivingNextIndices.forEach((nextIndex) => {
+            if (stationary.has(nextIndex))
+                return;
+            moved.push({ index: nextIndex, id: next[nextIndex].id });
+        });
+    }
+    return { added, changed, removed, moved, resultCount: next.length };
+}
+/**
+ * Whether two results hold the same items in the same order, by identity.
+ *
+ * Items are replaced rather than mutated wherever they come from, so identity is a sound answer to
+ * "unchanged" — and a wrong one is impossible, only a missed shortcut.
+ * @template T - The type of the items.
+ * @param previous - One result.
+ * @param next - The other.
+ * @returns `true` when the two are element-for-element the same objects.
+ */
+function holdsTheSameItems(previous, next) {
+    if (previous === next)
+        return true;
+    if (previous.length !== next.length)
+        return false;
+    return previous.every((item, index) => item === next[index]);
+}
+/**
+ * Applies a delta to the result it was computed against.
+ * @template T - The type of the items.
+ * @param previous - The result the delta is relative to. Not modified.
+ * @param delta - The delta to apply.
+ * @returns The resulting items.
+ */
+function applyQueryDelta(previous, delta) {
+    const removed = new Set(delta.removed);
+    const changedById = new Map(delta.changed.map(item => [item.id, item]));
+    const movedIds = new Set(delta.moved.map(({ id }) => id));
+    const stationary = [];
+    const byId = new Map();
+    previous.forEach((item) => {
+        if (removed.has(item.id))
+            return;
+        const current = changedById.get(item.id) ?? item;
+        byId.set(current.id, current);
+        if (!movedIds.has(current.id))
+            stationary.push(current);
+    });
+    // Insertions carry positions in the resulting array, so splicing them in ascending order lands
+    // every one of them at its final index — each is placed only after everything before it is there.
+    const insertions = [
+        ...delta.added.map(({ index, item }) => ({ index, item })),
+        ...delta.moved.map(({ index, id }) => ({ index, item: byId.get(id) })),
+    ].sort((a, b) => a.index - b.index); // eslint-disable-line unicorn/no-array-sort -- unavailable on Hermes
+    const result = stationary;
+    insertions.forEach(({ index, item }) => {
+        if (item == null)
+            return;
+        result.splice(index, 0, item);
+    });
+    return result;
+}

package/dist/base/core/src/utils/queryId.d.ts

@@ -0,0 +1,9 @@
+import type { QueryOptions } from '../DataAdapter';
+import type Selector from '../types/Selector';
+/**
+ * Generates a unique identifier for a query based on its selector and options.
+ * @param selector - The selector object.
+ * @param options - The query options object (optional).
+ * @returns A unique identifier string for the query.
+ */
+export default function queryId(selector: Selector<any>, options?: QueryOptions<any>): string;

package/dist/base/core/src/utils/queryId.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = queryId;
+/**
+ * Returns true when `options` is effectively "empty" for the purpose of queryId generation.
+ * Treats `undefined`/`null` as empty, and only considers plain objects with zero own enumerable keys as empty.
+ * Arrays and non-object values are not considered empty.
+ * @param options - Query options to test.
+ * @returns `true` if `options` is `null`/`undefined` or a plain object with no own keys; otherwise `false`.
+ */
+function isEmptyOptions(options) {
+    if (options == null)
+        return true;
+    if (typeof options !== 'object')
+        return false;
+    if (Array.isArray(options))
+        return false;
+    return Object.keys(options).length === 0;
+}
+// Stands in for absent options so they can be a `WeakMap` key like any other pair half.
+const noOptions = {};
+// Ids are asked for far more often than queries are created — every cursor read resolves its query
+// through one, and a single `postMessage` round trip goes through several. Serializing the same two
+// objects over and over is pure waste, so a pair of objects that has been seen before answers from
+// here. Keyed weakly on both halves: an entry lives exactly as long as the objects it describes,
+// and a selector built fresh at the call site simply misses and is collected again.
+//
+// The cache assumes a selector or options object is not mutated after it has been used to identify
+// a query. That already holds today for a different reason — a query is registered, cached and
+// looked up under the id its selector had at registration time, so mutating it afterwards loses the
+// query either way.
+const cache = new WeakMap();
+/**
+ * Generates a unique identifier for a query based on its selector and options.
+ * @param selector - The selector object.
+ * @param options - The query options object (optional).
+ * @returns A unique identifier string for the query.
+ */
+function queryId(selector, options) {
+    const isCacheable = selector != null && typeof selector === 'object'
+        && (options == null || typeof options === 'object');
+    if (!isCacheable) {
+        const optionsId = isEmptyOptions(options) ? -1 : JSON.stringify(options);
+        return `${JSON.stringify(selector)}:${optionsId}`;
+    }
+    const optionsKey = (options ?? noOptions);
+    const cachedForSelector = cache.get(selector);
+    const cached = cachedForSelector?.get(optionsKey);
+    if (cached != null)
+        return cached;
+    const selectorId = JSON.stringify(selector);
+    const optionsId = isEmptyOptions(options) ? -1 : JSON.stringify(options);
+    const id = `${selectorId}:${optionsId}`;
+    if (cachedForSelector) {
+        cachedForSelector.set(optionsKey, id);
+    }
+    else {
+        cache.set(selector, new WeakMap([[optionsKey, id]]));
+    }
+    return id;
+}

package/dist/base/core/src/utils/randomId.d.ts

@@ -0,0 +1,7 @@
+/**
+ * creates a random id
+ * @returns a random string of 16 characters
+ * @example
+ * randomId() // '1234567890abcdef'
+ */
+export default function randomId(): string;

package/dist/base/core/src/utils/randomId.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = randomId;
+/**
+ * creates a random id
+ * @returns a random string of 16 characters
+ * @example
+ * randomId() // '1234567890abcdef'
+ */
+function randomId() {
+    return Array.from({ length: 16 }, () => 'abcdefghijklmnopqrstuvwxyz0123456789'[Math.floor(Math.random() * 36)]).join('');
+}

package/dist/base/core/src/utils/reactiveOrAsync.d.ts

@@ -0,0 +1,59 @@
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Options that control execution mode (and potential future mode-specific behavior).
+ * Keep this minimal; you can extend it later (e.g. signal, timeoutMs, debugLabel).
+ */
+export type ModeOptions = {
+    async?: boolean;
+};
+/**
+ * A generator helper that makes TypeScript infer the “synchronous value type” for maybe-async expressions.
+ *
+ * Usage:
+ *   const doc = yield* unwrap(Collection.findOne(...))
+ *   const list = yield* unwrap(Collection.find(...).fetch())
+ *
+ * Runtime note:
+ *   This does not “unwrap” Promises by itself. It yields the value/Promise to the runner and returns the
+ *   value that the runner feeds back via `.next(...)`.
+ * @param value The value (or Promise of a value) to yield to the runner.
+ * @returns A generator that yields `value` and resolves to the runner-supplied unwrapped `T`.
+ */
+export declare function unwrap<T>(value: MaybePromise<T>): Generator<MaybePromise<T>, T, T>;
+/**
+ * Generator shape used by the factory.
+ *
+ * `TThis` is the type of `this` inside the generator.
+ * `Args` are the method parameters (excluding the mode flag).
+ * `TReturn` is the final return value of the workflow.
+ * `TNext` is the type that is yielded/awaited and fed back via `.next(...)`.
+ *
+ * Note:
+ * - For best inference at yield sites, prefer `yield* unwrap(expr)` for maybe-async expressions.
+ */
+export type ReactiveOrAsyncGen<TThis, Arguments extends any[], TReturn, TNext> = (this: TThis, a: boolean, ...args: Arguments) => Generator<MaybePromise<TNext>, TReturn, TNext>;
+/**
+ * The method type produced from the generator signature.
+ * Adds overloads so that `{ async: true }` yields a `Promise<...>` return type.
+ */
+export type ReactiveOrAsyncMethod<TThis, P extends any[], R, N> = {
+    (this: TThis, ...args: P): R;
+    (this: TThis, ...args: [...P, ModeOptions?]): MaybePromise<R>;
+    (this: TThis, ...args: [...P, {
+        async: true;
+    }]): Promise<R>;
+} & {
+    /** Exposes the underlying generator for composition via `yield* method.generator.call(this, a, ...)` */
+    generator: (this: TThis, a: boolean, ...args: P) => Generator<MaybePromise<N>, R, N>;
+};
+/**
+ * Factory that turns a generator workflow into a callable method that can run in sync (reactive) or async mode.
+ *
+ * Call style:
+ *   fn(a, b)                        -> sync/reactive return
+ *   await fn(a, b, { async: true }) -> async return
+ * @param gen Generator workflow. Receives `(a)` which indicates async mode and should `yield`/`yield* unwrap(...)`
+ *   any values that may be Promises.
+ * @returns A callable method with overloads plus a `.generator` property for composition.
+ */
+export default function reactiveOrAsync<TThis, P extends any[], R, N>(gen: (this: TThis, a: boolean, ...args: P) => Generator<MaybePromise<N>, R, N>): ReactiveOrAsyncMethod<TThis, P, R, N>;

package/dist/base/core/src/utils/reactiveOrAsync.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrap = unwrap;
+exports.default = reactiveOrAsync;
+/**
+ * A generator helper that makes TypeScript infer the “synchronous value type” for maybe-async expressions.
+ *
+ * Usage:
+ *   const doc = yield* unwrap(Collection.findOne(...))
+ *   const list = yield* unwrap(Collection.find(...).fetch())
+ *
+ * Runtime note:
+ *   This does not “unwrap” Promises by itself. It yields the value/Promise to the runner and returns the
+ *   value that the runner feeds back via `.next(...)`.
+ * @param value The value (or Promise of a value) to yield to the runner.
+ * @returns A generator that yields `value` and resolves to the runner-supplied unwrapped `T`.
+ */
+function unwrap(value) {
+    return (function* () {
+        return yield value;
+    })();
+}
+/**
+ * Internal: checks for thenables (Promise-like).
+ * @param value The value to test.
+ * @returns `true` if `value` looks like a Promise/thenable.
+ */
+function isThenable(value) {
+    return typeof value === 'object' && value !== null && typeof value.then === 'function';
+}
+/**
+ * Internal runner: executes a generator either synchronously (reactive) or asynchronously (imperative).
+ *
+ * - In sync mode, yielding a Promise is a programming error and throws.
+ * - In async mode, yielded Promises are awaited.
+ * @param thisArgument The `this` value to bind when invoking `gen`.
+ * @param mode Execution mode options.
+ * @param gen The generator workflow to run.
+ * @returns The workflow result (a plain value in sync mode, or a Promise in async mode).
+ */
+function runReactiveOrAsync(thisArgument, mode, gen) {
+    const a = !!mode?.async;
+    const it = gen.call(thisArgument, a);
+    if (!a) {
+        let step = it.next();
+        while (!step.done) {
+            const y = step.value;
+            if (isThenable(y))
+                throw new Error('Promise yielded in sync flow');
+            step = it.next(y);
+        }
+        return step.value;
+    }
+    return (async function () {
+        let step = it.next();
+        while (!step.done) {
+            const y = step.value;
+            const v = isThenable(y) ? await y : y;
+            step = it.next(v);
+        }
+        return step.value;
+    })();
+}
+/**
+ * Factory that turns a generator workflow into a callable method that can run in sync (reactive) or async mode.
+ *
+ * Call style:
+ *   fn(a, b)                        -> sync/reactive return
+ *   await fn(a, b, { async: true }) -> async return
+ * @param gen Generator workflow. Receives `(a)` which indicates async mode and should `yield`/`yield* unwrap(...)`
+ *   any values that may be Promises.
+ * @returns A callable method with overloads plus a `.generator` property for composition.
+ */
+function reactiveOrAsync(gen) {
+    /**
+     * The generated method wrapper.
+     * @param allArguments Method arguments, optionally ending with a `ModeOptions` object.
+     * @returns The workflow result (sync) or a Promise of the result (async).
+     */
+    function method(...allArguments) {
+        const last = allArguments.length > 0 ? allArguments.at(-1) : undefined;
+        const hasMode = typeof last === 'object'
+            && last !== null
+            && 'async' in (last);
+        const mode = hasMode ? last : undefined;
+        const parameters = (hasMode ? allArguments.slice(0, -1) : allArguments);
+        return runReactiveOrAsync(this, mode, function* (a) {
+            return yield* gen.call(this, a, ...parameters);
+        });
+    }
+    method.generator = gen;
+    return method;
+}

package/dist/base/core/src/utils/serializeValue.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Serializes a value into a string representation.
+ * Handles various types, including strings, numbers, booleans, dates, and objects.
+ * Falls back to JSON stringification for unsupported types.
+ * @param value - The value to serialize.
+ *   - Strings are returned as-is.
+ *   - Numbers and booleans are converted to their string representation.
+ *   - Dates are converted to ISO string format.
+ *   - Other values are stringified using `JSON.stringify`.
+ * @returns A string representation of the value.
+ */
+export default function serializeValue(value: any): string | null;

package/dist/base/core/src/utils/serializeValue.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = serializeValue;
+/**
+ * Serializes a value into a string representation.
+ * Handles various types, including strings, numbers, booleans, dates, and objects.
+ * Falls back to JSON stringification for unsupported types.
+ * @param value - The value to serialize.
+ *   - Strings are returned as-is.
+ *   - Numbers and booleans are converted to their string representation.
+ *   - Dates are converted to ISO string format.
+ *   - Other values are stringified using `JSON.stringify`.
+ * @returns A string representation of the value.
+ */
+function serializeValue(value) {
+    if (value == null)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return value.toString();
+    if (typeof value === 'boolean')
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    return JSON.stringify(value);
+}

package/dist/base/core/src/utils/set.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sets a value at a specified path within an object. Creates nested structures
+ * (arrays or objects) as needed to set the value at the correct location. Supports
+ * deleting the key if the value is `undefined` and the `deleteIfUndefined` flag is set to `true`.
+ * @template T - The type of the object to modify.
+ * @template K - The type of the value to set.
+ * @param object - The object to modify. The object is mutated directly.
+ * @param path - The path (dot or bracket notation) where the value should be set.
+ * @param value - The value to set at the specified path.
+ * @param deleteIfUndefined - A boolean indicating whether to delete the key if the value is `undefined` (default: `false`).
+ * @returns The modified object.
+ */
+export default function set<T extends object, K>(object: T, path: string, value: K, deleteIfUndefined?: boolean): T;

package/dist/base/core/src/utils/set.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = set;
+/**
+ * Sets a value at a specified path within an object. Creates nested structures
+ * (arrays or objects) as needed to set the value at the correct location. Supports
+ * deleting the key if the value is `undefined` and the `deleteIfUndefined` flag is set to `true`.
+ * @template T - The type of the object to modify.
+ * @template K - The type of the value to set.
+ * @param object - The object to modify. The object is mutated directly.
+ * @param path - The path (dot or bracket notation) where the value should be set.
+ * @param value - The value to set at the specified path.
+ * @param deleteIfUndefined - A boolean indicating whether to delete the key if the value is `undefined` (default: `false`).
+ * @returns The modified object.
+ */
+function set(object, path, value, deleteIfUndefined = false) {
+    if (object == null)
+        return object;
+    const segments = path.split(/[.[\]]/g);
+    if (segments[0] === '')
+        segments.shift();
+    if (segments.at(-1) === '')
+        segments.pop();
+    const apply = (node) => {
+        if (segments.length > 1) {
+            const key = segments.shift();
+            const nextIsNumber = !Number.isNaN(Number.parseInt(segments[0], 10));
+            if (node[key] === undefined) {
+                node[key] = nextIsNumber ? [] : {};
+            }
+            apply(node[key]);
+        }
+        else {
+            if (deleteIfUndefined && value === undefined) {
+                delete node[segments[0]];
+                return;
+            }
+            node[segments[0]] = value;
+        }
+    };
+    apply(object);
+    return object;
+}

package/dist/base/core/src/utils/sortItems.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sorts an array of items based on multiple fields and their specified sort order.
+ * Uses the `fast-sort` library for efficient sorting.
+ * @template T - The type of the items in the array.
+ * @param items - The array of items to be sorted.
+ * @param sortFields - An object defining the sort order for each field.
+ *   - Keys are the field names, and values are either `1` (ascending) or `-1` (descending).
+ * @returns A new array of items sorted based on the specified fields and their order.
+ */
+export default function sortItems<T extends Record<string, any>>(items: T[], sortFields: {
+    [P in keyof T]?: -1 | 1;
+} & Record<string, -1 | 1>): T[];