applesauce-core 5.1.0 → 6.0.0

package/dist/helpers/url.d.ts

@@ -20,8 +20,5 @@ export declare function ensureProtocol(url: string, protocol?: string): string;
 export declare function ensureWebSocketURL<T extends string | URL>(url: T): T;
 /** Converts a domain or WS URL to a HTTP URL */
 export declare function ensureHttpURL<T extends string | URL>(url: T): T;
-/**
- * Normalizes a string into a relay URL
- * Does not remove the trailing slash
- */
+/** Normalizes a string into a cleaner URL by dropping port if its not needed */
 export declare function normalizeURL<T extends string | URL>(url: T): T;

package/dist/helpers/url.js

@@ -80,10 +80,7 @@ export function ensureHttpURL(url) {
     // @ts-expect-error
     return typeof url === "string" ? p.toString() : p;
 }
-/**
- * Normalizes a string into a relay URL
- * Does not remove the trailing slash
- */
+/** Normalizes a string into a cleaner URL by dropping port if its not needed */
 export function normalizeURL(url) {
     let p = new URL(url);
     // Remove any double slashes

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-export * from "./event-factory/index.js";
+export * from "./factories/index.js";
+export * from "./casts/index.js";
 export * from "./event-store/index.js";
 export * from "./logger.js";
 export * from "./observable/index.js";
 export * as Helpers from "./helpers/index.js";
 export * as Models from "./models/index.js";
 export * as Operations from "./operations/index.js";
+export * as Factories from "./factories/index.js";

package/dist/index.js

@@ -1,7 +1,10 @@
-export * from "./event-factory/index.js";
+// Export from factories
+export * from "./factories/index.js";
+export * from "./casts/index.js";
 export * from "./event-store/index.js";
 export * from "./logger.js";
 export * from "./observable/index.js";
 export * as Helpers from "./helpers/index.js";
 export * as Models from "./models/index.js";
 export * as Operations from "./operations/index.js";
+export * as Factories from "./factories/index.js";

package/dist/observable/catch-error-inline.d.ts

@@ -0,0 +1,3 @@
+import { OperatorFunction } from "rxjs";
+/** Catches any errors and includes them in the observable stream */
+export declare function catchErrorInline<T extends unknown>(): OperatorFunction<T, T | Error>;

package/dist/observable/catch-error-inline.js

@@ -0,0 +1,5 @@
+import { catchError, of } from "rxjs";
+/** Catches any errors and includes them in the observable stream */
+export function catchErrorInline() {
+    return catchError((err) => (err instanceof Error ? of(err) : of(new Error(err.message))));
+}

package/dist/observable/chainable.d.ts

@@ -0,0 +1,36 @@
+import { Observable } from "rxjs";
+/**
+ * Wraps an Observable in a Proxy that enables property chaining.
+ * When accessing a property ending with `$`, it uses switchMap to chain
+ * to that property's observable value.
+ * When accessing a non-observable property, it returns an Observable of that property's value.
+ */
+export declare function chainable<T>(observable: Observable<T>): ChainableObservable<T>;
+/**
+ * Helper type to extract nullable parts (undefined/null) from a type
+ */
+type NullableParts<T> = Extract<T, undefined | null>;
+/**
+ * Helper type to get the property type, preserving nullable parts from the parent type
+ */
+type PropChain<T, K extends keyof NonNullable<T>> = NonNullable<T>[K] | NullableParts<T>;
+/**
+ * A chainable Observable type that allows property chaining.
+ * This type maps all properties to chainable observables:
+ * - Properties ending with $: extracts inner type from Observable<U> → ChainableObservable<U>
+ * - Other properties: uses property type directly → ChainableObservable<PropertyType>
+ *
+ * Note: TypeScript has limitations inferring through Proxy types. For better
+ * type inference, you may need to explicitly type the result:
+ */
+export type ChainableObservable<T> = Observable<T> & Omit<{
+    [K in keyof NonNullable<T> as K extends string ? K : never]: K extends `${infer _}$` ? NonNullable<T>[K] extends Observable<infer U> ? ChainableObservable<U | NullableParts<T>> : never : ChainableObservable<PropChain<T, K>>;
+}, "$first" | "$last"> & {
+    /** Returns a promise that resolves with the first value or rejects with a timeout error */
+    $first(first?: number): Promise<NonNullable<T>>;
+    $first<V>(first?: number, fallback?: V): Promise<NonNullable<T> | V>;
+    /** Returns a promise that resolves with the last value or rejects with a timeout error */
+    $last(max?: number): Promise<NonNullable<T>>;
+    $last<V>(max?: number, fallback?: V): Promise<NonNullable<T> | V>;
+};
+export {};

package/dist/observable/chainable.js

@@ -0,0 +1,72 @@
+import { filter, firstValueFrom, isObservable, lastValueFrom, map, of, switchMap, timeout } from "rxjs";
+/**
+ * A symbol used to mark an Observable as chainable
+ */
+const CHAINABLE_CACHE_SYMBOL = Symbol.for("chainable-cache");
+/**
+ * Wraps an Observable in a Proxy that enables property chaining.
+ * When accessing a property ending with `$`, it uses switchMap to chain
+ * to that property's observable value.
+ * When accessing a non-observable property, it returns an Observable of that property's value.
+ */
+export function chainable(observable) {
+    // Create a Proxy that intercepts property access
+    const proxy = new Proxy(observable, {
+        get(target$, prop) {
+            const cache = observable[CHAINABLE_CACHE_SYMBOL] ||
+                (observable[CHAINABLE_CACHE_SYMBOL] = {});
+            // Forward all Observable methods and properties
+            if (prop in target$ || typeof prop === "symbol") {
+                const value = target$[prop];
+                // If it's a function, bind it to the target
+                if (typeof value === "function")
+                    return value.bind(target$);
+                return value;
+            }
+            if (typeof prop === "string") {
+                // Return cached observable if it exists
+                const cached = cache[prop];
+                if (cached)
+                    return cached;
+                // Otherwise, create a new observable
+                let prop$;
+                // Extra observalbe helpers to make it easier to work with observables
+                if (prop === "$first") {
+                    return (...args) => firstValueFrom(target$.pipe(filter((v) => v !== undefined && v !== null), args.length === 2
+                        ? timeout({ first: args[0], with: () => of(args[1]) })
+                        : timeout({ first: args[0] ?? 10_000 })));
+                }
+                else if (prop === "$last") {
+                    return (...args) => lastValueFrom(target$.pipe(filter((v) => v !== undefined && v !== null), args.length === 2
+                        ? timeout({ first: args[0], with: () => of(args[1]) })
+                        : timeout({ first: args[0] ?? 10_000 })));
+                }
+                // Handle property access for properties ending with $
+                else if (prop.endsWith("$")) {
+                    // Use switchMap to chain to the nested observable
+                    prop$ = target$.pipe(switchMap((target) => {
+                        const value = target === undefined || target === null ? target : target[prop];
+                        // If value is an observable, return it
+                        if (isObservable(value))
+                            return value;
+                        // Otherwise wrap it in an observable
+                        else
+                            return of(value);
+                    }));
+                }
+                // For non-$ properties, return an Observable of the property value
+                else {
+                    prop$ = target$.pipe(
+                    // Access the property on the value if target is not undefined or null
+                    map((target) => (target === undefined || target === null ? target : target[prop])));
+                }
+                // Make the chained observable chainable too
+                const observable = chainable(prop$);
+                cache[prop] = observable;
+                return observable;
+            }
+            throw new Error(`Unable to access property "${prop}" on chainable observable`);
+        },
+    });
+    return proxy;
+}

package/dist/observable/combine-latest-by-index.d.ts

@@ -0,0 +1,10 @@
+import { Observable } from "rxjs";
+/**
+ * Dynamic counterpart to `switchMap(() => combineLatest(...))` for arrays,
+ * with stable branches by index.
+ *
+ * Each array index gets its own long-lived branch (`of(value).pipe(...)`
+ * equivalent), and branches are only created/removed when indices are
+ * added/removed.
+ */
+export declare function combineLatestByIndex<T, R>(project: (source$: Observable<T>, index: number) => Observable<R>): (source$: Observable<readonly T[]>) => Observable<R[]>;

package/dist/observable/combine-latest-by-index.js

@@ -0,0 +1,121 @@
+import { Observable, Subject } from "rxjs";
+/** Sentinel to distinguish "no value yet" from a real value */
+const NOT_YET = Symbol("NOT_YET");
+/**
+ * Dynamic counterpart to `switchMap(() => combineLatest(...))` for arrays,
+ * with stable branches by index.
+ *
+ * Each array index gets its own long-lived branch (`of(value).pipe(...)`
+ * equivalent), and branches are only created/removed when indices are
+ * added/removed.
+ */
+export function combineLatestByIndex(project) {
+    return (source$) => new Observable((subscriber) => {
+        const slots = [];
+        let sourceCompleted = false;
+        let batchingSourceNext = false;
+        let emittedDuringBatch = false;
+        function checkComplete() {
+            if (!sourceCompleted)
+                return;
+            for (const slot of slots) {
+                if (!slot.completed)
+                    return;
+            }
+            subscriber.complete();
+        }
+        function tryEmit() {
+            for (const slot of slots) {
+                if (slot.value === NOT_YET)
+                    return;
+            }
+            subscriber.next(slots.map((slot) => slot.value));
+        }
+        function createSlot(index) {
+            const input = new Subject();
+            const slot = { input, value: NOT_YET, completed: false };
+            let projected$;
+            try {
+                projected$ = project(input, index);
+            }
+            catch (err) {
+                input.complete();
+                subscriber.error(err);
+                return undefined;
+            }
+            slot.sub = projected$.subscribe({
+                next(value) {
+                    slot.value = value;
+                    if (batchingSourceNext) {
+                        emittedDuringBatch = true;
+                        return;
+                    }
+                    tryEmit();
+                },
+                error(err) {
+                    subscriber.error(err);
+                },
+                complete() {
+                    slot.completed = true;
+                    checkComplete();
+                },
+            });
+            return slot;
+        }
+        const sourceSub = source$.subscribe({
+            next(items) {
+                batchingSourceNext = true;
+                emittedDuringBatch = false;
+                while (slots.length > items.length) {
+                    const slot = slots.pop();
+                    if (!slot)
+                        break;
+                    slot.sub?.unsubscribe();
+                    slot.input.complete();
+                }
+                while (slots.length < items.length) {
+                    const slot = createSlot(slots.length);
+                    if (!slot) {
+                        batchingSourceNext = false;
+                        return;
+                    }
+                    slots.push(slot);
+                }
+                for (let i = 0; i < items.length; i++) {
+                    if (subscriber.closed) {
+                        batchingSourceNext = false;
+                        return;
+                    }
+                    const slot = slots[i];
+                    if (!slot) {
+                        batchingSourceNext = false;
+                        return;
+                    }
+                    slot.input.next(items[i]);
+                }
+                // Emit once for this source update if possible.
+                if (emittedDuringBatch || items.length === 0)
+                    tryEmit();
+                batchingSourceNext = false;
+            },
+            error(err) {
+                subscriber.error(err);
+            },
+            complete() {
+                sourceCompleted = true;
+                for (const slot of slots) {
+                    slot.input.complete();
+                }
+                checkComplete();
+            },
+        });
+        return () => {
+            sourceSub.unsubscribe();
+            for (const slot of slots) {
+                slot.sub?.unsubscribe();
+                slot.input.complete();
+            }
+            slots.length = 0;
+        };
+    });
+}

package/dist/observable/combine-latest-by-key.d.ts

@@ -0,0 +1,10 @@
+import { Observable, type OperatorFunction } from "rxjs";
+/**
+ * Dynamic counterpart to `switchMap(() => combineLatest(...))` for records,
+ * with stable branches by key.
+ *
+ * Each record key gets its own long-lived branch. Branches are only
+ * created/removed when keys are added/removed; value updates are pushed through
+ * the existing key branch.
+ */
+export declare function combineLatestByKey<Input extends Record<string, unknown>, R>(project: (source$: Observable<Input[Extract<keyof Input, string>]>, key: Extract<keyof Input, string>) => Observable<R>): OperatorFunction<Input, Record<Extract<keyof Input, string>, R>>;

package/dist/observable/combine-latest-by-key.js

@@ -0,0 +1,136 @@
+import { Observable, Subject } from "rxjs";
+/** Sentinel to distinguish "no value yet" from a real value */
+const NOT_YET = Symbol("NOT_YET");
+/**
+ * Dynamic counterpart to `switchMap(() => combineLatest(...))` for records,
+ * with stable branches by key.
+ *
+ * Each record key gets its own long-lived branch. Branches are only
+ * created/removed when keys are added/removed; value updates are pushed through
+ * the existing key branch.
+ */
+export function combineLatestByKey(project) {
+    return (source$) => new Observable((subscriber) => {
+        const slots = new Map();
+        let sourceCompleted = false;
+        let currentKeys = [];
+        let batchingSourceNext = false;
+        let emittedDuringBatch = false;
+        function checkComplete() {
+            if (!sourceCompleted)
+                return;
+            for (const slot of slots.values()) {
+                if (!slot.completed)
+                    return;
+            }
+            subscriber.complete();
+        }
+        function tryEmit() {
+            for (const key of currentKeys) {
+                const slot = slots.get(key);
+                if (!slot || slot.value === NOT_YET)
+                    return;
+            }
+            const out = {};
+            for (const key of currentKeys) {
+                const slot = slots.get(key);
+                if (!slot)
+                    return;
+                out[key] = slot.value;
+            }
+            subscriber.next(out);
+            if (batchingSourceNext)
+                emittedDuringBatch = true;
+        }
+        function createSlot(key) {
+            const input = new Subject();
+            const slot = { input, value: NOT_YET, completed: false };
+            let child$;
+            try {
+                child$ = project(input, key);
+            }
+            catch (err) {
+                input.complete();
+                subscriber.error(err);
+                return undefined;
+            }
+            slot.sub = child$.subscribe({
+                next(value) {
+                    slot.value = value;
+                    if (batchingSourceNext) {
+                        emittedDuringBatch = true;
+                        return;
+                    }
+                    tryEmit();
+                },
+                error(err) {
+                    subscriber.error(err);
+                },
+                complete() {
+                    slot.completed = true;
+                    checkComplete();
+                },
+            });
+            return slot;
+        }
+        const sourceSub = source$.subscribe({
+            next(input) {
+                batchingSourceNext = true;
+                emittedDuringBatch = false;
+                const entries = Object.entries(input);
+                currentKeys = entries.map(([key]) => key);
+                const newKeysSet = new Set(currentKeys);
+                for (const [key, slot] of slots) {
+                    if (!newKeysSet.has(key)) {
+                        slot.sub?.unsubscribe();
+                        slot.input.complete();
+                        slots.delete(key);
+                    }
+                }
+                for (const key of currentKeys) {
+                    if (!slots.has(key)) {
+                        const slot = createSlot(key);
+                        if (!slot) {
+                            batchingSourceNext = false;
+                            return;
+                        }
+                        slots.set(key, slot);
+                    }
+                }
+                for (const [key, value] of entries) {
+                    if (subscriber.closed) {
+                        batchingSourceNext = false;
+                        return;
+                    }
+                    const slot = slots.get(key);
+                    if (!slot) {
+                        batchingSourceNext = false;
+                        return;
+                    }
+                    slot.input.next(value);
+                }
+                if (emittedDuringBatch || entries.length === 0)
+                    tryEmit();
+                batchingSourceNext = false;
+            },
+            error(err) {
+                subscriber.error(err);
+            },
+            complete() {
+                sourceCompleted = true;
+                for (const slot of slots.values()) {
+                    slot.input.complete();
+                }
+                checkComplete();
+            },
+        });
+        return () => {
+            sourceSub.unsubscribe();
+            for (const slot of slots.values()) {
+                slot.sub?.unsubscribe();
+                slot.input.complete();
+            }
+            slots.clear();
+        };
+    });
+}

package/dist/observable/combine-latest-by-value.d.ts

@@ -0,0 +1,10 @@
+import { Observable, type OperatorFunction } from "rxjs";
+/**
+ * Dynamic counterpart to `switchMap((values) => combineLatest(values.map(...)))`
+ * for arrays, with stable branches by value.
+ *
+ * A single branch is created per unique array value (Map key semantics) and is
+ * only created/removed when values are added/removed across emissions. Duplicate
+ * values in the same array share the same branch.
+ */
+export declare function combineLatestByValue<T, R>(project: (value: T) => Observable<R>): OperatorFunction<readonly T[], Map<T, R>>;

package/dist/observable/combine-latest-by-value.js

@@ -0,0 +1,117 @@
+import { Observable } from "rxjs";
+/** Sentinel to distinguish "no value yet" from a real value */
+const NOT_YET = Symbol("NOT_YET");
+/**
+ * Dynamic counterpart to `switchMap((values) => combineLatest(values.map(...)))`
+ * for arrays, with stable branches by value.
+ *
+ * A single branch is created per unique array value (Map key semantics) and is
+ * only created/removed when values are added/removed across emissions. Duplicate
+ * values in the same array share the same branch.
+ */
+export function combineLatestByValue(project) {
+    return (source$) => new Observable((subscriber) => {
+        const slots = new Map();
+        let sourceCompleted = false;
+        let currentValues = [];
+        let batchingSourceNext = false;
+        function checkComplete() {
+            if (!sourceCompleted)
+                return;
+            for (const slot of slots.values()) {
+                if (!slot.completed)
+                    return;
+            }
+            subscriber.complete();
+        }
+        function tryEmit() {
+            for (const value of currentValues) {
+                const slot = slots.get(value);
+                if (!slot || slot.value === NOT_YET)
+                    return;
+            }
+            const out = new Map();
+            for (const value of currentValues) {
+                const slot = slots.get(value);
+                if (!slot)
+                    return;
+                out.set(value, slot.value);
+            }
+            subscriber.next(out);
+        }
+        function createSlot(value) {
+            const slot = { value: NOT_YET, completed: false };
+            let child$;
+            try {
+                child$ = project(value);
+            }
+            catch (err) {
+                subscriber.error(err);
+                return undefined;
+            }
+            slot.sub = child$.subscribe({
+                next(nextValue) {
+                    slot.value = nextValue;
+                    if (batchingSourceNext) {
+                        return;
+                    }
+                    tryEmit();
+                },
+                error(err) {
+                    subscriber.error(err);
+                },
+                complete() {
+                    slot.completed = true;
+                    checkComplete();
+                },
+            });
+            return slot;
+        }
+        const sourceSub = source$.subscribe({
+            next(input) {
+                batchingSourceNext = true;
+                const uniqueValues = [];
+                const nextValueSet = new Set();
+                for (const value of input) {
+                    if (nextValueSet.has(value))
+                        continue;
+                    nextValueSet.add(value);
+                    uniqueValues.push(value);
+                }
+                currentValues = uniqueValues;
+                for (const [value, slot] of slots) {
+                    if (!nextValueSet.has(value)) {
+                        slot.sub?.unsubscribe();
+                        slots.delete(value);
+                    }
+                }
+                for (const value of currentValues) {
+                    if (!slots.has(value)) {
+                        const slot = createSlot(value);
+                        if (!slot) {
+                            batchingSourceNext = false;
+                            return;
+                        }
+                        slots.set(value, slot);
+                    }
+                }
+                tryEmit();
+                batchingSourceNext = false;
+            },
+            error(err) {
+                subscriber.error(err);
+            },
+            complete() {
+                sourceCompleted = true;
+                checkComplete();
+            },
+        });
+        return () => {
+            sourceSub.unsubscribe();
+            for (const slot of slots.values()) {
+                slot.sub?.unsubscribe();
+            }
+            slots.clear();
+        };
+    });
+}

package/dist/observable/combine-latest-by.d.ts

@@ -0,0 +1,16 @@
+import { type OperatorFunction } from "rxjs";
+/** Operator object type: one branch operator per output key. */
+type CombineLatestByObjectOperators<Input, Output extends Record<string, unknown>> = {
+    [K in keyof Output]: OperatorFunction<Input, Output[K]>;
+};
+/** Operator tuple type: one branch operator per output index. */
+type CombineLatestByArrayOperators<Input, Output extends readonly unknown[]> = {
+    [K in keyof Output]: OperatorFunction<Input, Output[K]>;
+};
+/**
+ * Branches a source through multiple operators and combines branch outputs with
+ * `combineLatest` semantics.
+ */
+export declare function combineLatestBy<Input, Output extends Record<string, unknown>>(operators: CombineLatestByObjectOperators<Input, Output>): OperatorFunction<Input, Output>;
+export declare function combineLatestBy<Input, Output extends readonly unknown[]>(operators: CombineLatestByArrayOperators<Input, Output>): OperatorFunction<Input, Output>;
+export {};

package/dist/observable/combine-latest-by.js

@@ -0,0 +1,12 @@
+import { combineLatest, connect } from "rxjs";
+export function combineLatestBy(operators) {
+    return connect((shared$) => {
+        if (Array.isArray(operators)) {
+            const branches = operators.map((op) => shared$.pipe(op));
+            return combineLatest(branches);
+        }
+        const objectOperators = operators;
+        const branches = Object.fromEntries(Object.entries(objectOperators).map(([key, op]) => [key, shared$.pipe(op)]));
+        return combineLatest(branches);
+    });
+}

package/dist/observable/index.d.ts

@@ -1,10 +1,16 @@
-export { firstValueFrom, lastValueFrom, combineLatest, merge } from "rxjs";
-export { Observable, Subject, BehaviorSubject, ReplaySubject } from "rxjs";
+export { BehaviorSubject, combineLatest, firstValueFrom, lastValueFrom, merge, Observable, ReplaySubject, Subject, } from "rxjs";
+export * from "./catch-error-inline.js";
+export * from "./chainable.js";
+export * from "./combine-latest-by-index.js";
+export * from "./combine-latest-by-key.js";
+export * from "./combine-latest-by-value.js";
+export * from "./combine-latest-by.js";
 export * from "./defined.js";
 export * from "./get-observable-value.js";
-export * from "./map-events-to-timeline.js";
 export * from "./map-events-to-store.js";
+export * from "./map-events-to-timeline.js";
+export * from "./relay-selection.js";
 export * from "./simple-timeout.js";
+export * from "./timeout-with-ignore.js";
 export * from "./watch-event-updates.js";
 export * from "./with-immediate-value.js";
-export * from "./relay-selection.js";

package/dist/observable/index.js

@@ -1,11 +1,17 @@
 // Re-export some useful rxjs functions
-export { firstValueFrom, lastValueFrom, combineLatest, merge } from "rxjs";
-export { Observable, Subject, BehaviorSubject, ReplaySubject } from "rxjs";
+export { BehaviorSubject, combineLatest, firstValueFrom, lastValueFrom, merge, Observable, ReplaySubject, Subject, } from "rxjs";
+export * from "./catch-error-inline.js";
+export * from "./chainable.js";
+export * from "./combine-latest-by-index.js";
+export * from "./combine-latest-by-key.js";
+export * from "./combine-latest-by-value.js";
+export * from "./combine-latest-by.js";
 export * from "./defined.js";
 export * from "./get-observable-value.js";
-export * from "./map-events-to-timeline.js";
 export * from "./map-events-to-store.js";
+export * from "./map-events-to-timeline.js";
+export * from "./relay-selection.js";
 export * from "./simple-timeout.js";
+export * from "./timeout-with-ignore.js";
 export * from "./watch-event-updates.js";
 export * from "./with-immediate-value.js";
-export * from "./relay-selection.js";