@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Types.d.ts

@@ -3,18 +3,29 @@
  *
  * @module
  */
-import * as Kysely from "kysely";
-import type { TypeName } from "./Type.js";
 /**
  * A function that receives a value and returns nothing.
  *
  * Use for event handlers, observers, and async completion handlers.
  *
- * ### Example
+ * ### Completion callbacks
  *
  * ```ts
- * const onComplete: Callback<string> = (value) => console.log(value);
- * const queue = new Set<Callback<Result<Data, Error>>>();
+ * import { ok, type Callback, type Result } from "@evolu/common";
+ *
+ * const completedValues: Array<string> = [];
+ * const onComplete: Callback<string> = (value) => {
+ *   completedValues.push(value);
+ * };
+ * const queue = new Set<Callback<Result<string, Error>>>();
+ * queue.add((result) => {
+ *   if (result.ok) completedValues.push(result.value);
+ * });
+ *
+ * onComplete("direct");
+ * for (const callback of queue) callback(ok("queued"));
+ *
+ * expect(completedValues).toEqual(["direct", "queued"]);
  * ```
  */
 export type Callback<T> = (value: T) => void;
@@ -23,13 +34,29 @@ export type Callback<T> = (value: T) => void;
  *
  * Use for subscriptions or callbacks that need abort-time teardown.
  *
- * ### Example
+ * ### Subscription teardown
  *
  * ```ts
+ * import type { CallbackWithTeardown } from "@evolu/common";
+ *
+ * interface EventSource {
+ *   readonly start: () => void;
+ *   readonly stop: () => void;
+ * }
+ *
+ * const events: Array<string> = [];
+ * const source: EventSource = {
+ *   start: () => events.push("started"),
+ *   stop: () => events.push("stopped"),
+ * };
  * const subscribe: CallbackWithTeardown<EventSource> = (source) => {
  *   source.start();
- *   return () => source.stop();
+ *   return source.stop;
  * };
+ * const teardown = subscribe(source);
+ * if (teardown) teardown();
+ *
+ * expect(events).toEqual(["started", "stopped"]);
  * ```
  */
 export type CallbackWithTeardown<T> = (value: T) => void | (() => void);
@@ -38,13 +65,14 @@ export type CallbackWithTeardown<T> = (value: T) => void | (() => void);
  *
  * A predicate starts with an 'is' prefix, e.g., `isEven`.
  *
- * ### Example
+ * ### Filtering values
  *
  * ```ts
+ * import type { Predicate } from "@evolu/common";
+ *
  * const isEven: Predicate<number> = (n) => n % 2 === 0;
  *
- * const numbers = [1, 2, 3, 4];
- * const evenNumbers = numbers.filter(isEven); // [2, 4]
+ * expect([1, 2, 3, 4].filter(isEven)).toEqual([2, 4]);
  * ```
  */
 export type Predicate<T> = (value: T) => boolean;
@@ -53,33 +81,40 @@ export type Predicate<T> = (value: T) => boolean;
  *
  * Useful for callbacks that need both the element and its position.
  *
- * ### Example
+ * ### Filtering by position
  *
  * ```ts
+ * import type { PredicateWithIndex } from "@evolu/common";
+ *
  * const isEvenIndex: PredicateWithIndex<string> = (value, index) =>
  *   index % 2 === 0;
  *
- * const items = ["a", "b", "c", "d"];
- * const evenIndexItems = items.filter(isEvenIndex); // ["a", "c"]
+ * expect(["a", "b", "c", "d"].filter(isEvenIndex)).toEqual(["a", "c"]);
  * ```
  */
 export type PredicateWithIndex<T> = (value: T, index: number) => boolean;
 /**
  * A type guard function that refines type `A` to a narrower type `B`.
  *
- * ### Example
+ * ### Narrowing a value
  *
  * ```ts
- * type Animal = { name: string };
- * type Dog = Animal & { breed: string };
+ * import type { Refinement } from "@evolu/common";
+ *
+ * interface Animal {
+ *   readonly name: string;
+ * }
+ * interface Dog extends Animal {
+ *   readonly breed: string;
+ * }
  *
  * const isDog: Refinement<Animal, Dog> = (animal): animal is Dog =>
  *   "breed" in animal;
+ * const dog: Dog = { name: "Dog", breed: "Beagle" };
+ * const animal: Animal = dog;
+ * if (!isDog(animal)) throw new Error("Expected a dog");
  *
- * const animal: Animal = { name: "Dog", breed: "Beagle" };
- * if (isDog(animal)) {
- *   console.log(animal.breed); // Safe access to `breed`
- * }
+ * expect(animal.breed).toBe("Beagle");
  * ```
  */
 export type Refinement<in A, out B extends A> = (a: A) => a is B;
@@ -90,40 +125,112 @@ export type Refinement<in A, out B extends A> = (a: A) => a is B;
  * Useful for callbacks that need both the element and its position while
  * maintaining type narrowing.
  *
- * ### Example
+ * ### Indexed refinement
  *
  * ```ts
- * type Item = { type: "number" | "string"; value: unknown };
- *
- * const isNumberItem: RefinementWithIndex<Item, Item & { type: "number" }> =
- *   (item, index): item is Item & { type: "number" } =>
- *     index > 0 && item.type === "number";
+ * import { partitionArray, type RefinementWithIndex } from "@evolu/common";
  *
- * const items: ReadonlyArray<Item> = [...];
+ * type Item = {
+ *   readonly type: "number" | "string";
+ *   readonly value: unknown;
+ * };
+ * type NumberItem = Item & { readonly type: "number" };
+ *
+ * const isNumberItem: RefinementWithIndex<Item, NumberItem> = (
+ *   item,
+ *   index,
+ * ): item is NumberItem => index > 0 && item.type === "number";
+ * const items: ReadonlyArray<Item> = [
+ *   { type: "number", value: 1 },
+ *   { type: "number", value: 2 },
+ * ];
  * const [numbers, others] = partitionArray(items, isNumberItem);
+ *
+ * expectTypeOf(numbers).toEqualTypeOf<ReadonlyArray<NumberItem>>();
+ * expect(numbers[0]?.value).toBe(2);
+ * expect(others[0]?.value).toBe(1);
  * ```
  */
 export type RefinementWithIndex<in A, out B extends A> = (a: A, index: number) => a is B;
+/**
+ * Realm-neutral runtime identity for a TypeScript interface.
+ *
+ * Extend this interface and add its runtime evidence with {@link instance} when
+ * constructing a value. Unlike JavaScript `instanceof`, the identity does not
+ * depend on a constructor or prototype and therefore survives realms, package
+ * duplication, object spreading, and structured cloning.
+ *
+ * The marker is intentionally forgeable. It identifies values created by
+ * trusted constructors; it is not structural validation or a security
+ * boundary.
+ *
+ * ### Adding runtime identity
+ *
+ * ```ts
+ * import { instance, type Instance } from "@evolu/common";
+ *
+ * interface Foo extends Instance<"Foo"> {
+ *   readonly value: string;
+ * }
+ *
+ * const foo: Foo = {
+ *   ...instance("Foo"),
+ *   value: "value",
+ * };
+ *
+ * expect(foo["~evolu/instance"]).toBe("Foo");
+ * ```
+ */
+export interface Instance<Name extends string> {
+    readonly "~evolu/instance": Name;
+}
+/** Creates the runtime identity property required by {@link Instance}. */
+export declare const instance: <const Name extends string>(name: Name) => Instance<Name>;
+/**
+ * Creates a realm-neutral predicate for one {@link Instance} name.
+ *
+ * The identity must be stored directly on the value; inherited markers are
+ * ignored.
+ *
+ * The explicit value type can include the rest of an interface whose trusted
+ * constructors attach the matching identity.
+ *
+ * ### Checking runtime identity
+ *
+ * ```ts
+ * import { instance, isInstance, type Instance } from "@evolu/common";
+ *
+ * interface Foo extends Instance<"Foo"> {
+ *   readonly value: string;
+ * }
+ *
+ * const isFoo = isInstance<Foo>("Foo");
+ * const value: unknown = { ...instance("Foo"), value: "value" };
+ *
+ * expect(isFoo(value)).toBe(true);
+ * ```
+ */
+export declare const isInstance: <Value extends Instance<string>>(name: Value["~evolu/instance"]) => (value: unknown) => value is Value;
 /**
  * Makes properties optional if they accept `null` as a value.
  *
  * For each property in `T`, if `null` is a valid value for that property, the
  * property will be made optional in the resulting type.
  *
- * ### Example
+ * ### Optional nullable properties
  *
  * ```ts
+ * import type { NullablePartial } from "@evolu/common";
+ *
  * type Example = {
  *   required: string;
  *   optionalWithNull: string | null;
  * };
  *
- * type Result = NullablePartial<Example>;
- * // Result is:
- * // {
- * //   required: string;
- * //   optionalWithNull?: string | null;
- * // }
+ * expectTypeOf<NullablePartial<Example>>().toEqualTypeOf<{
+ *   required: string;
+ *   optionalWithNull?: string | null;
+ * }>();
  * ```
  */
 export type NullablePartial<T, NK extends keyof T = {
@@ -131,6 +238,10 @@ export type NullablePartial<T, NK extends keyof T = {
 }[keyof T], NP = Pick<T, Exclude<keyof T, NK>> & Partial<Pick<T, NK>>> = {
     [K in keyof NP]: NP[K];
 };
+/** A value with a numeric length. */
+export interface ValueWithLength {
+    readonly length: number;
+}
 /**
  * String, number, bigint, boolean, undefined, null
  *
@@ -148,13 +259,8 @@ export type Literal = string | number | bigint | boolean | undefined | null;
  * - True -> boolean
  */
 export type WidenLiteral<T extends Literal> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends bigint ? bigint : T;
-/**
- * Removes `readonly` modifier from all properties of a type.
- *
- * Useful for constructing immutable objects step-by-step (e.g. builder pattern)
- * before casting them back to the readonly type.
- */
-export type Mutable<T> = {
+/** Removes `readonly` modifier from all properties of a type. */
+export type Writable<T> = {
     -readonly [P in keyof T]: T[P];
 };
 /**
@@ -163,19 +269,23 @@ export type Mutable<T> = {
  * This utility forces TypeScript to "flatten" an intersection type into a
  * single object type so that tooltips and error messages are easier to read.
  *
- * ### Example
+ * ### Flattening an intersection
  *
  * ```ts
- * type A = { a: string } & { b: number };
- * // Without Simplify, TypeScript may display A as:
- * // { a: string } & { b: number }
+ * import type { Simplify } from "@evolu/common";
  *
+ * type A = { a: string } & { b: number };
  * type B = Simplify<A>;
- * // B is equivalent to:
- * // { a: string; b: number }
+ *
+ * expectTypeOf<B>().toEqualTypeOf<{
+ *   a: string;
+ *   b: number;
+ * }>();
  * ```
  */
-export type Simplify<T> = Kysely.Simplify<T>;
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 /**
  * Makes a specific property of an object optional while keeping others
  * unchanged.
@@ -187,21 +297,21 @@ export type PartialProp<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
  * Use when a function may complete synchronously or asynchronously depending on
  * runtime conditions (e.g., cache hit vs network fetch).
  *
- * ### Example
+ * ### Sync and async completion
  *
  * ```ts
- * const getData = (id: string): Awaitable<Data> => {
- *   const cached = cache.get(id);
- *   if (cached) return cached; // Sync path
- *   return fetchData(id); // Async path
- * };
+ * import { isPromiseLike, type Awaitable } from "@evolu/common";
  *
- * // Always works
- * const data = await getData(id);
+ * const cache = new Map([["cached", "from cache"]]);
+ * const getData = (id: string): Awaitable<string> =>
+ *   cache.get(id) ?? Promise.resolve(`fetched ${id}`);
  *
- * // Or optimize for sync path
- * const result = getData(id);
- * const data = isPromiseLike(result) ? await result : result;
+ * const fetched = await getData("missing");
+ * const result = getData("cached");
+ * const cached = isPromiseLike(result) ? await result : result;
+ *
+ * expect(fetched).toBe("fetched missing");
+ * expect(cached).toBe("from cache");
  * ```
  */
 export type Awaitable<T> = T | PromiseLike<T>;
@@ -211,33 +321,35 @@ export type Awaitable<T> = T | PromiseLike<T>;
  * Use with {@link Awaitable} to conditionally `await` only when necessary,
  * avoiding microtask overhead for synchronous values.
  *
- * ### Example
+ * ### Conditional awaiting
  *
  * ```ts
- * const validate = (id: string): Awaitable<boolean> => {
- *   const cached = cache.get(id);
- *   if (cached !== undefined) return cached; // Sync path
- *   return fetchValidation(id); // Async path
- * };
+ * import { isPromiseLike, type Awaitable } from "@evolu/common";
  *
- * const result = validate(id);
+ * const cache = new Map([["cached", true]]);
+ * const validate = (id: string): Awaitable<boolean> =>
+ *   cache.get(id) ?? Promise.resolve(false);
+ *
+ * const result = validate("cached");
  * const isValid = isPromiseLike(result) ? await result : result;
+ *
+ * expect(isValid).toBe(true);
  * ```
  */
 export declare const isPromiseLike: <T>(value: Awaitable<T>) => value is PromiseLike<T>;
-/** Single digit 0-9. Useful for template literal type validation. */
+/** Decimal digit from `"0"` to `"9"`. */
 export type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
-/** Digit 1-9. Useful for template literal type validation. */
+/** Decimal digit from `"1"` to `"9"`. */
 export type Digit1To9 = Exclude<Digit, "0">;
-/** Numeric string 1-6. Useful for days validation. */
+/** Decimal string from `"1"` to `"6"`. */
 export type Digit1To6 = "1" | "2" | "3" | "4" | "5" | "6";
-/** Numeric string 1-23. Useful for hours validation. */
+/** Decimal string from `"1"` to `"23"`. */
 export type Digit1To23 = Digit1To9 | `1${Digit}` | `2${"0" | "1" | "2" | "3"}`;
-/** Numeric string 1-51. Useful for weeks validation. */
+/** Decimal string from `"1"` to `"51"`. */
 export type Digit1To51 = Digit1To9 | `${"1" | "2" | "3" | "4"}${Digit}` | `5${"0" | "1"}`;
-/** Numeric string 1-99. Useful for years validation. */
+/** Decimal string from `"1"` to `"99"`. */
 export type Digit1To99 = Digit1To9 | `${Digit1To9}${Digit}`;
-/** Numeric string 1-59. Useful for minutes, seconds validation. */
+/** Decimal string from `"1"` to `"59"`. */
 export type Digit1To59 = Digit1To9 | `1${Digit}` | `2${Digit}` | `3${Digit}` | `4${Digit}` | `5${Digit}`;
 /** Numeric literal 1-99. */
 export type Int1To99 = NumberFromString<Digit1To99>;
@@ -249,57 +361,37 @@ export type Int1To100 = Int1To99 | 100;
  * Used by {@link Int1To99}.
  */
 export type NumberFromString<T extends string> = T extends `${infer N extends number}` ? N : never;
+/** Creates a readable compiler-facing error message. */
+export type CompileTimeError<Context extends string, Message extends string> = `⛔ ${Context} error: ${Message}`;
+/** Returns whether a type is a union. */
+export type IsUnion<T, Whole = T> = [T] extends [never] ? false : T extends Whole ? [Whole] extends [T] ? false : true : never;
+/** Returns every property key present in any member of a union. */
+export type KeysOfUnion<T> = T extends T ? keyof T : never;
 /** Converts a union to an intersection. */
 export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** Intersects the parameter types of a union of unary functions. */
+export type ParameterIntersection<T> = [T] extends [(value: infer I) => void] ? I : unknown;
 /**
  * Removes keys from each member of a union.
  *
  * Use when {@link Omit} would collapse a discriminated union into a single
  * shared shape.
  *
- * ### Example
+ * ### Preserving discriminated unions
  *
  * ```ts
+ * import type { DistributiveOmit } from "@evolu/common";
+ *
  * type Event =
  *   | { type: "a"; a: string; shared: number }
  *   | { type: "b"; b: number; shared: number };
  *
  * type Payload = DistributiveOmit<Event, "shared">;
- * // { type: "a"; a: string } | { type: "b"; b: number }
- * ```
- */
-export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
-/**
- * Extracts members of a discriminated union by their `type` literal.
- *
- * Constrains `TType` to valid `type` values, so typos fail at the type argument
- * instead of silently producing `never`.
- *
- * ### Example
  *
- * ```ts
- * type Message =
- *   | { readonly type: "Create"; readonly id: string }
- *   | { readonly type: "Delete"; readonly id: string };
- *
- * type CreateMessage = ExtractType<Message, "Create">;
- * // { readonly type: "Create"; readonly id: string }
- *
- * // Type error: "Cretae" is not a valid Message type
- * type _Typo = ExtractType<Message, "Cretae">;
+ * expectTypeOf<Payload>().toEqualTypeOf<
+ *   { type: "a"; a: string } | { type: "b"; b: number }
+ * >();
  * ```
  */
-export type ExtractType<TUnion extends {
-    readonly type: TypeName;
-}, TType extends TUnion["type"]> = Extract<TUnion, {
-    readonly type: TType;
-}>;
-/**
- * Constrains `T` to only contain keys not present in `Existing`.
- *
- * Use as a generic constraint to prevent overriding existing properties.
- */
-export type NewKeys<T, Existing> = {
-    [K in keyof T]: K extends keyof Existing ? never : T[K];
-};
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 //# sourceMappingURL=Types.d.ts.map

package/dist/src/Types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../src/Types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../src/Types.ts"],"names":[],"mappings":"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"}

package/dist/src/Types.js

@@ -3,24 +3,55 @@
  *
  * @module
  */
-import * as Kysely from "kysely";
+/** Creates the runtime identity property required by {@link Instance}. */
+export const instance = (name) => ({ "~evolu/instance": name });
+/**
+ * Creates a realm-neutral predicate for one {@link Instance} name.
+ *
+ * The identity must be stored directly on the value; inherited markers are
+ * ignored.
+ *
+ * The explicit value type can include the rest of an interface whose trusted
+ * constructors attach the matching identity.
+ *
+ * ### Checking runtime identity
+ *
+ * ```ts
+ * import { instance, isInstance, type Instance } from "@evolu/common";
+ *
+ * interface Foo extends Instance<"Foo"> {
+ *   readonly value: string;
+ * }
+ *
+ * const isFoo = isInstance<Foo>("Foo");
+ * const value: unknown = { ...instance("Foo"), value: "value" };
+ *
+ * expect(isFoo(value)).toBe(true);
+ * ```
+ */
+export const isInstance = (name) => (value) => value !== null &&
+    typeof value === "object" &&
+    globalThis.Object.hasOwn(value, "~evolu/instance") &&
+    value["~evolu/instance"] === name;
 /**
  * Type guard to check if a value is a {@link PromiseLike}.
  *
  * Use with {@link Awaitable} to conditionally `await` only when necessary,
  * avoiding microtask overhead for synchronous values.
  *
- * ### Example
+ * ### Conditional awaiting
  *
  * ```ts
- * const validate = (id: string): Awaitable<boolean> => {
- *   const cached = cache.get(id);
- *   if (cached !== undefined) return cached; // Sync path
- *   return fetchValidation(id); // Async path
- * };
+ * import { isPromiseLike, type Awaitable } from "@evolu/common";
+ *
+ * const cache = new Map([["cached", true]]);
+ * const validate = (id: string): Awaitable<boolean> =>
+ *   cache.get(id) ?? Promise.resolve(false);
  *
- * const result = validate(id);
+ * const result = validate("cached");
  * const isValid = isPromiseLike(result) ? await result : result;
+ *
+ * expect(isValid).toBe(true);
  * ```
  */
 export const isPromiseLike = (value) => typeof value?.then === "function";

package/dist/src/WebSocket.d.ts

@@ -3,11 +3,11 @@
  *
  * @module
  */
-import type { Result } from "./Result.js";
-import type { Schedule } from "./Schedule.js";
-import type { RetryError, Task } from "./Task.js";
-import type { Millis } from "./Time.js";
-import { type Typed } from "./Type.js";
+import type { Result } from "./Result.ts";
+import type { Schedule } from "./Schedule.ts";
+import type { RetryError, Task } from "./Task.ts";
+import type { Millis } from "./Time.ts";
+import { type Typed } from "./Type.ts";
 /**
  * WebSocket with auto-reconnect.
  *
@@ -42,20 +42,42 @@ import { type Typed } from "./Type.js";
  *   - A Blob (default: "blob")
  *   - An ArrayBuffer ("arraybuffer")
  *
- * ### Example
+ * ### Connecting and sending
  *
  * ```ts
- * const ws = await run(
- *   createWebSocket("wss://example.com", {
- *     onMessage: (data) => console.log("Received:", data),
- *     onOpen: () => console.log("Connected"),
- *     onClose: () => console.log("Disconnected"),
- *   }),
- * );
- * if (ws.ok) {
- *   ws.value.send("Hello");
- *   // Later: await ws.value[Symbol.asyncDispose]();
- * }
+ * import {
+ *   createRun,
+ *   createWebSocket,
+ *   testCreateWebSocket,
+ *   type CreateWebSocket,
+ *   type Task,
+ *   type WebSocketSendError,
+ * } from "@evolu/common";
+ *
+ * const connectAndSend =
+ *   (
+ *     createSocket: CreateWebSocket = createWebSocket,
+ *   ): Task<void, WebSocketSendError> =>
+ *   async (run) => {
+ *     await using socket = await run.ok(
+ *       createSocket("wss://example.com", {
+ *         protocols: ["evolu"],
+ *         binaryType: "arraybuffer",
+ *         onOpen: () => console.log("Connected"),
+ *         onMessage: (data) => console.log("Received:", data),
+ *         onClose: () => console.log("Disconnected"),
+ *       }),
+ *     );
+ *     return socket.send("Hello");
+ *   };
+ *
+ * const socketFactory = testCreateWebSocket();
+ * await using run = createRun();
+ *
+ * expectOk(await run(connectAndSend(socketFactory)), undefined);
+ * expect(socketFactory.sentMessages).toEqual([
+ *   { url: "wss://example.com", data: "Hello" },
+ * ]);
  * ```
  */
 export interface WebSocket extends AsyncDisposable {
@@ -104,12 +126,8 @@ export interface WebSocketOptions {
     /** Callback when message data is received. */
     readonly onMessage?: (data: string | ArrayBuffer | Blob) => void;
     /**
-     * Retry schedule for reconnection. Defaults to:
-     *
-     * ```ts
-     * // A jittered, capped, unlimited exponential backoff.
-     * jitter(1)(maxDelay("30s")(exponential("100ms")));
-     * ```
+     * Retry schedule for reconnection. Defaults to
+     * {@link webSocketReconnectSchedule}.
      */
     readonly schedule?: Schedule<Millis, WebSocketRetryError>;
     /**
@@ -146,6 +164,13 @@ export type WebSocketRetryError = WebSocketConnectError | WebSocketConnectionClo
 export interface WebSocketConnectionCloseError extends Typed<"WebSocketConnectionCloseError"> {
     readonly event: CloseEvent;
 }
+/**
+ * Default WebSocket reconnect schedule.
+ *
+ * Uses unlimited exponential backoff with a 100ms base, 30s cap, and full
+ * jitter.
+ */
+export declare const webSocketReconnectSchedule: Schedule<Millis, WebSocketRetryError>;
 /** Create a new {@link WebSocket}. */
 export declare const createWebSocket: CreateWebSocket;
 /**