@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Types.ts

@@ -4,19 +4,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;
@@ -26,13 +36,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);
@@ -42,13 +68,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;
@@ -58,14 +85,15 @@ 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;
@@ -73,19 +101,25 @@ 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;
@@ -97,17 +131,30 @@ 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 };
+ * import { partitionArray, type RefinementWithIndex } from "@evolu/common";
  *
- * const isNumberItem: RefinementWithIndex<Item, Item & { type: "number" }> =
- *   (item, index): item is Item & { type: "number" } =>
- *     index > 0 && item.type === "number";
- *
- * 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> = (
@@ -115,26 +162,96 @@ export type RefinementWithIndex<in A, out B extends 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 const instance = <const Name extends string>(
+  name: Name,
+): 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 =
+  <Value extends Instance<string>>(name: Value["~evolu/instance"]) =>
+  (value: unknown): value is Value =>
+    value !== null &&
+    typeof value === "object" &&
+    globalThis.Object.hasOwn(value, "~evolu/instance") &&
+    (value as Instance<string>)["~evolu/instance"] === name;
+
 /**
  * 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<
@@ -145,6 +262,11 @@ export type NullablePartial<
   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
  *
@@ -172,13 +294,8 @@ export type WidenLiteral<T extends Literal> = T extends string
         ? 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];
 };
 
@@ -188,19 +305,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
@@ -215,21 +336,21 @@ export type PartialProp<T, K extends keyof T> = Omit<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";
+ *
+ * const cache = new Map([["cached", "from cache"]]);
+ * const getData = (id: string): Awaitable<string> =>
+ *   cache.get(id) ?? Promise.resolve(`fetched ${id}`);
  *
- * // Always works
- * const data = await getData(id);
+ * const fetched = await getData("missing");
+ * const result = getData("cached");
+ * const cached = isPromiseLike(result) ? await result : result;
  *
- * // Or optimize for sync path
- * const result = getData(id);
- * const data = isPromiseLike(result) ? await result : result;
+ * expect(fetched).toBe("fetched missing");
+ * expect(cached).toBe("from cache");
  * ```
  */
 export type Awaitable<T> = T | PromiseLike<T>;
@@ -240,17 +361,19 @@ 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 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 = <T>(
@@ -258,33 +381,33 @@ export const isPromiseLike = <T>(
 ): value is PromiseLike<T> =>
   typeof (value as PromiseLike<T> | null | undefined)?.then === "function";
 
-/** 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-9
   | `1${Digit}` // 10-19
   | `2${"0" | "1" | "2" | "3"}`; // 20-23
 
-/** Numeric string 1-51. Useful for weeks validation. */
+/** Decimal string from `"1"` to `"51"`. */
 export type Digit1To51 =
   | Digit1To9 // 1-9
   | `${"1" | "2" | "3" | "4"}${Digit}` // 10-49
   | `5${"0" | "1"}`; // 50-51
 
-/** Numeric string 1-99. Useful for years validation. */
+/** Decimal string from `"1"` to `"99"`. */
 export type Digit1To99 =
   | Digit1To9 // 1-9
   | `${Digit1To9}${Digit}`; // 10-99
 
-/** Numeric string 1-59. Useful for minutes, seconds validation. */
+/** Decimal string from `"1"` to `"59"`. */
 export type Digit1To59 =
   | Digit1To9 // 1-9
   | `1${Digit}` // 10-19
@@ -307,6 +430,24 @@ export type Int1To100 = Int1To99 | 100;
 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
@@ -314,57 +455,33 @@ export type UnionToIntersection<U> = (
   ? 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 }
+ *
+ * expectTypeOf<Payload>().toEqualTypeOf<
+ *   { 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">;
- * ```
- */
-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];
-};