@evolu/common 7.4.0 → 8.0.0-next.0

package/src/Types.ts

@@ -1,10 +1,41 @@
 /**
- * TypeScript utility types
+ * TypeScript utility types.
  *
  * @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
+ *
+ * ```ts
+ * const onComplete: Callback<string> = (value) => console.log(value);
+ * const queue = new Set<Callback<Result<Data, Error>>>();
+ * ```
+ */
+export type Callback<T> = (value: T) => void;
+
+/**
+ * A function that receives a value and optionally returns a teardown function.
+ *
+ * Use for subscriptions or callbacks that need abort-time teardown.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const subscribe: CallbackWithTeardown<EventSource> = (source) => {
+ *   source.start();
+ *   return () => source.stop();
+ * };
+ * ```
+ */
+export type CallbackWithTeardown<T> = (value: T) => void | (() => void);
 
 /**
  * Checks a condition on a value and returns a boolean.
@@ -114,12 +145,6 @@ export type NullablePartial<
   NP = Pick<T, Exclude<keyof T, NK>> & Partial<Pick<T, NK>>,
 > = { [K in keyof NP]: NP[K] };
 
-/**
- * A type alias for `never` that is used intentionally when casting is not
- * needed and unit tests exist to ensure correctness.
- */
-export type IntentionalNever = never;
-
 /**
  * String, number, bigint, boolean, undefined, null
  *
@@ -147,6 +172,16 @@ 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> = {
+  -readonly [P in keyof T]: T[P];
+};
+
 /**
  * Simplify an intersection type into a single mapped type.
  *
@@ -173,3 +208,163 @@ export type Simplify<T> = Kysely.Simplify<T>;
  */
 export type PartialProp<T, K extends keyof T> = Omit<T, K> &
   Partial<Pick<T, K>>;
+
+/**
+ * A value that can be awaited.
+ *
+ * Use when a function may complete synchronously or asynchronously depending on
+ * runtime conditions (e.g., cache hit vs network fetch).
+ *
+ * ### Example
+ *
+ * ```ts
+ * const getData = (id: string): Awaitable<Data> => {
+ *   const cached = cache.get(id);
+ *   if (cached) return cached; // Sync path
+ *   return fetchData(id); // Async path
+ * };
+ *
+ * // Always works
+ * const data = await getData(id);
+ *
+ * // Or optimize for sync path
+ * const result = getData(id);
+ * const data = isPromiseLike(result) ? await result : result;
+ * ```
+ */
+export type Awaitable<T> = T | PromiseLike<T>;
+
+/**
+ * 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
+ *
+ * ```ts
+ * const validate = (id: string): Awaitable<boolean> => {
+ *   const cached = cache.get(id);
+ *   if (cached !== undefined) return cached; // Sync path
+ *   return fetchValidation(id); // Async path
+ * };
+ *
+ * const result = validate(id);
+ * const isValid = isPromiseLike(result) ? await result : result;
+ * ```
+ */
+export const isPromiseLike = <T>(
+  value: Awaitable<T>,
+): value is PromiseLike<T> =>
+  typeof (value as PromiseLike<T> | null | undefined)?.then === "function";
+
+/** Single digit 0-9. Useful for template literal type validation. */
+export type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+
+/** Digit 1-9. Useful for template literal type validation. */
+export type Digit1To9 = Exclude<Digit, "0">;
+
+/** Numeric string 1-6. Useful for days validation. */
+export type Digit1To6 = "1" | "2" | "3" | "4" | "5" | "6";
+
+/** Numeric string 1-23. Useful for hours validation. */
+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. */
+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. */
+export type Digit1To99 =
+  | Digit1To9 // 1-9
+  | `${Digit1To9}${Digit}`; // 10-99
+
+/** Numeric string 1-59. Useful for minutes, seconds validation. */
+export type Digit1To59 =
+  | Digit1To9 // 1-9
+  | `1${Digit}` // 10-19
+  | `2${Digit}` // 20-29
+  | `3${Digit}` // 30-39
+  | `4${Digit}` // 40-49
+  | `5${Digit}`; // 50-59
+
+/** Numeric literal 1-99. */
+export type Int1To99 = NumberFromString<Digit1To99>;
+
+/** Numeric literal 1-100. */
+export type Int1To100 = Int1To99 | 100;
+
+/**
+ * Parses a numeric literal type from a string literal.
+ *
+ * Used by {@link Int1To99}.
+ */
+export type NumberFromString<T extends string> =
+  T extends `${infer N extends number}` ? N : 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;
+
+/**
+ * Removes keys from each member of a union.
+ *
+ * Use when {@link Omit} would collapse a discriminated union into a single
+ * shared shape.
+ *
+ * ### Example
+ *
+ * ```ts
+ * 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">;
+ * ```
+ */
+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];
+};