@evolu/common 8.1.0 → 8.3.0

package/src/Number.ts

@@ -11,21 +11,86 @@ import type { Result } from "./Result.ts";
 import { err, ok } from "./Result.ts";
 import {
   brand,
+  Digit1To9,
+  Digit1To99,
   lessThanOrEqualTo,
   onePositiveInt,
   NonNegativeInt,
   PositiveInt,
   Ratio,
+  templateLiteral,
+  union,
 } from "./Type.ts";
-import type {
-  Digit,
-  Digit1To9,
-  Digit1To99,
-  Predicate,
-  WidenLiteral,
-} from "./Types.ts";
+import type { Predicate, WidenLiteral } from "./Types.ts";
+
+/** Integer literal from `1` to `99`. */
+export type Int1To99 = Digit1To99 extends `${infer Value extends number}`
+  ? Value
+  : never;
+
+/** Integer literal from `1` to `100`. */
+export type Int1To100 = Int1To99 | 100;
+
+/**
+ * Integer literal from 0 to 100 or {@link NonNegativeInt}.
+ *
+ * Convenience input accepting integer literals from 0 to 100 or an
+ * already-validated {@link NonNegativeInt} for larger or dynamic values.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   NonNegativeInt,
+ *   type Int0To100OrNonNegativeInt,
+ * } from "@evolu/common";
+ *
+ * const literal: Int0To100OrNonNegativeInt = 10;
+ * const validated: Int0To100OrNonNegativeInt = NonNegativeInt.orThrow(101);
+ *
+ * assert(literal === 10);
+ * assert(validated === 101);
+ * ```
+ */
+export type Int0To100OrNonNegativeInt = 0 | Int1To100 | NonNegativeInt;
 
-/** Percentage represented as a readable literal or a validated ratio. */
+/**
+ * {@link Int1To100} or {@link PositiveInt}.
+ *
+ * Convenience input accepting integer literals from 1 to 100 or an
+ * already-validated {@link PositiveInt} for larger or dynamic values.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { PositiveInt, type Int1To100OrPositiveInt } from "@evolu/common";
+ *
+ * const literal: Int1To100OrPositiveInt = 10;
+ * const validated: Int1To100OrPositiveInt = PositiveInt.orThrow(101);
+ *
+ * assert(literal === 10);
+ * assert(validated === 101);
+ * ```
+ */
+export type Int1To100OrPositiveInt = Int1To100 | PositiveInt;
+
+/**
+ * {@link PercentageLiteral} or {@link Ratio}.
+ *
+ * Convenience input accepting a readable {@link PercentageLiteral} or a
+ * validated {@link Ratio}. APIs normalize it to `Ratio`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { Ratio, jitter } from "@evolu/common";
+ *
+ * const readableJitter = jitter("50%");
+ * const computedJitter = jitter(Ratio.orThrow(0.5));
+ *
+ * expectTypeOf(readableJitter).toEqualTypeOf(computedJitter);
+ * ```
+ */
 export type Percentage = PercentageLiteral | Ratio;
 
 /**
@@ -34,8 +99,18 @@ export type Percentage = PercentageLiteral | Ratio;
  * Decimal literals support one decimal place. Use {@link Ratio} for computed
  * values or greater precision.
  */
-export type PercentageLiteral =
-  "0%" | "100%" | `${Digit1To99}%` | `${Digit | Digit1To99}.${Digit1To9}%`;
+export const PercentageLiteral = /*#__PURE__*/ union(
+  "0%",
+  "100%",
+  /*#__PURE__*/ templateLiteral(Digit1To99, "%"),
+  /*#__PURE__*/ templateLiteral(
+    /*#__PURE__*/ union("0", Digit1To99),
+    ".",
+    Digit1To9,
+    "%",
+  ),
+);
+export type PercentageLiteral = typeof PercentageLiteral.Output;
 
 /** Converts a {@link Percentage} to its numeric {@link Ratio}. */
 export const percentageToRatio = (percentage: Percentage): Ratio =>
@@ -45,10 +120,6 @@ export const percentageToRatio = (percentage: Percentage): Ratio =>
 
 export const increment = (n: number): number => n + 1;
 
-/** Increments a positive integer, saturating at the maximum safe integer. */
-export const incrementPositiveInt = (n: PositiveInt): PositiveInt =>
-  PositiveInt.orNull(increment(n)) ?? n;
-
 export const decrement = (n: number): number => n - 1;
 
 /** Clamps a number within a given range. */

package/src/Object.ts

@@ -279,6 +279,8 @@ export function createMutableRecord<
   K extends string = string,
   V = unknown,
 >(): Record<K, V>;
+
+/** Creates a mutable null-prototype copy of an object. */
 export function createMutableRecord<T extends object>(
   source: T,
 ): { -readonly [K in keyof T]: T[K] };

package/src/RefCount.ts

@@ -88,6 +88,8 @@ export interface CreateRefCountByKeyOptions<
 
 /** Creates {@link RefCountByKey}. */
 export function createRefCountByKey<TKey = unknown>(): RefCountByKey<TKey>;
+
+/** Creates {@link RefCountByKey} with custom logical key lookup. */
 export function createRefCountByKey<TKey, L>(
   options: CreateRefCountByKeyOptions<TKey, L>,
 ): RefCountByKey<TKey>;

package/src/Relation.ts

@@ -181,6 +181,8 @@ export interface CreateRelationOptions<A, B, LA = A, LB = B> {
 
 /** Creates a {@link Relation}. */
 export function createRelation<A, B>(): Relation<A, B>;
+
+/** Creates a {@link Relation} with custom logical key lookups. */
 export function createRelation<A, B, LA, LB>(
   options: CreateRelationOptions<A, B, LA, LB>,
 ): Relation<A, B>;
@@ -371,6 +373,8 @@ export interface RefCountedRelation<A, B> {
 
 /** Creates a {@link RefCountedRelation}. */
 export function createRefCountedRelation<A, B>(): RefCountedRelation<A, B>;
+
+/** Creates a {@link RefCountedRelation} with custom logical key lookups. */
 export function createRefCountedRelation<A, B, LA, LB>(
   options: CreateRelationOptions<A, B, LA, LB>,
 ): RefCountedRelation<A, B>;

package/src/Resource.ts

@@ -705,6 +705,8 @@ export function createSharedResourceByKey<
 >(
   create: (key: K) => Task<T, never, D>,
 ): Task<SharedResourceByKey<K, T>, never, D>;
+
+/** Creates {@link SharedResourceByKey} with lookup or lifecycle options. */
 export function createSharedResourceByKey<K, T extends Resource, D, L = K>(
   create: (key: K) => Task<T, never, D>,
   options: SharedResourceByKeyOptions<K, L>,