@evolu/common 6.0.1-preview.33 → 6.0.1-preview.35

package/src/Sqlite.ts

@@ -511,10 +511,14 @@ const drawSqliteQueryPlan = (rows: Array<SqliteQueryPlanRow>): string =>
  * SQLite represents boolean values using `0` (false) and `1` (true) instead of
  * a dedicated boolean type.
  *
- * Use {@link sqliteTrue} and {@link sqliteFalse} constants for better
- * readability.
- *
  * See: https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
+ *
+ * ### Tips
+ *
+ * - Use {@link sqliteTrue} and {@link sqliteFalse} constants for better
+ *   readability.
+ * - Use {@link booleanToSqliteBoolean} and {@link sqliteBooleanToBoolean} for
+ *   converting between JavaScript booleans and SQLite boolean values.
  */
 export const SqliteBoolean = union(0, 1);
 export type SqliteBoolean = typeof SqliteBoolean.Type;
@@ -532,3 +536,29 @@ export const sqliteTrue = 1;
  * See {@link SqliteBoolean}.
  */
 export const sqliteFalse = 0;
+
+/**
+ * Converts a JavaScript boolean to a {@link SqliteBoolean}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isActive = true;
+ * const sqlValue = booleanToSqliteBoolean(isActive); // Returns 1
+ * ```
+ */
+export const booleanToSqliteBoolean = (value: boolean): SqliteBoolean =>
+  value ? sqliteTrue : sqliteFalse;
+
+/**
+ * Converts a {@link SqliteBoolean} to a JavaScript boolean.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const sqlValue: SqliteBoolean = 1;
+ * const bool = sqliteBooleanToBoolean(sqlValue); // Returns true
+ * ```
+ */
+export const sqliteBooleanToBoolean = (value: SqliteBoolean): boolean =>
+  value === sqliteTrue;

package/src/Type.ts

@@ -3,10 +3,7 @@
  *
  * Evolu {@link Type} is like a type guard that returns typed errors (via
  * {@link Result}) instead of throwing. We either get a safely typed value or a
- * precise, composable error value telling us exactly why validation failed.
- *
- * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
- * interoperability with 40+ validation-compatible tools and frameworks.
+ * composable typed error telling us exactly why validation failed.
  *
  * Why another validation library?
  *
@@ -15,16 +12,19 @@
  *   messages.
  * - **Consistent constraints via {@link Brand}** – every constraint becomes part
  *   of the type.
- * - **Selective validation** – parent validations are skipped when already proved
- *   by typing.
- * - **Simple, top-down implementation** – readable source code from top to bottom
- *   with no hidden magic; just plain functions and composition.
+ * - **Skippable validation** – parent validations can be skipped when already
+ *   proved by types.
+ * - **Simple, top-down implementation** – readable source code from top to
+ *   bottom.
+ * - **No user-land chaining DSL** – prepared for TC39 Hack pipes.
+ *
+ * A distinctive feature of Evolu Type compared to other validation libraries is
+ * that it returns typed errors rather than string messages. This allows
+ * TypeScript to enforce that all validation errors are handled by type
+ * checking, significantly improving the developer experience.
  *
- * TODO: Refactor Type factories and composition for Hack pipes compatibility.
- * Currently, brand factories like `minLength(min)(Type)` use constraint-first
- * currying. For optimal Hack pipe support, these should be refactored to
- * `minLength(Type, min)` to enable: `Type |> minLength(%, 1) |> maxLength(%,
- * 100)`
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
+ * interoperability with 40+ validation-compatible tools and frameworks.
  *
  * ### Base Types Quick Start
  *
@@ -175,6 +175,29 @@
  * reverse transforms would not buy much. We may revisit this if we can design a
  * minimal, 100% safe API that preserves simplicity.
  *
+ * ### Prepared for TC39 Hack Pipes
+ *
+ * Take a look how `SimplePassword` is defined:
+ *
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper) and read well, but with
+ * TC39 Hack pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
+ * Note `minLength` and `maxLength` are curried because they are factories.
+ *
  * @module
  */
 
@@ -189,6 +212,7 @@ import { isPlainObject } from "./Object.js";
 import { hasNodeBuffer } from "./Platform.js";
 import { err, getOrNull, getOrThrow, ok, Result, trySync } from "./Result.js";
 import { safelyStringifyUnknownValue } from "./String.js";
+import type { TimeDep } from "./Time.js";
 import type { Literal, Simplify, WidenLiteral } from "./Types.js";
 import { IntentionalNever } from "./Types.js";
 
@@ -1501,7 +1525,7 @@ export const base64UrlToUint8Array: (str: Base64Url) => Uint8Array =
  * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
  * `_`). See `UrlSafeString` for details.
  *
- * The string must be between 1 and 42 characters.
+ * The string must be between 1 and 64 characters.
  *
  * ### Example
  *
@@ -1517,7 +1541,7 @@ export const base64UrlToUint8Array: (str: Base64Url) => Uint8Array =
  * @category String
  */
 export const SimpleName = brand("SimpleName", UrlSafeString, (value) =>
-  value.length >= 1 && value.length <= 42
+  value.length >= 1 && value.length <= 64
     ? ok(value)
     : err<SimpleNameError>({ type: "SimpleName", value }),
 );
@@ -1527,6 +1551,25 @@ export interface SimpleNameError extends TypeError<"SimpleName"> {}
 /**
  * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
  *
+ * Take a look how `SimplePassword` is defined:
+ *
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper), but with TC39 Hack
+ * pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
  * @category String
  */
 export const SimplePassword = brand(
@@ -1547,41 +1590,27 @@ export const formatSimplePasswordError = (
   );
 
 /**
- * Globally unique identifier.
- *
- * **Evolu Id** is 16 random bytes from a cryptographically secure random
- * generator, encoded as 22-character Base64Url string. This provides strong
- * collision resistance for distributed ID generation.
- *
- * ### Design Rationale
- *
- * Why Evolu Id over alternatives:
- *
- * - **NanoID**: No standard binary serialization format, and uses only ~126 bits
- *   of entropy (21 characters from 64-symbol alphabet) compared to Evolu Id's
- *   128 bits.
- * - **UUID (v4)**: String format is 36 characters (with hyphens) compared to
- *   Evolu Id's 22 characters. While UUIDs can be stored as 16 bytes, their
- *   standard string representation is verbose.
- * - **UUID v7**: Includes timestamp in the ID, which leaks information about when
- *   data was created. This is a privacy concern for local-first applications
- *   where creation time must remain private.
- *
- * Evolu Id provides 128 bits of entropy, compact string representation (22
- * characters), standard and native string serialization (Base64Url), and no
- * privacy leaks.
- *
- * ### Future Consideration
- *
- * For database-heavy workloads where insert performance is critical, a hybrid
- * approach could be considered: `timestamp ^ H(cluster_id, timestamp >> N)`
- * where H is a keyed hash function and N is a configurable parameter. This
- * would maintain spatial locality for database caches (improving insert
- * performance by an order of magnitude) while adding entropy to prevent
- * timestamp leakage and correlation across systems. The parameter N would allow
- * trading off cache locality (larger N = better locality) versus entropy
- * distribution. See https://brooker.co.za/blog/2025/10/22/uuidv7.html for
- * details on this approach.
+ * Evolu Id: 16 bytes encoded as a 22‑character Base64Url string.
+ *
+ * There are three ways to create an Evolu Id:
+ *
+ * - {@link createId} – default cryptographically secure random bytes
+ *   (privacy‑preserving)
+ * - {@link createIdFromString} – deterministic: first 16 bytes of SHA‑256 of a
+ *   string
+ * - {@link createIdAsUuidv7} – optional: embeds timestamp bits (UUID v7 layout)
+ *
+ * Privacy: the default random Id does not leak creation time and is safe to
+ * share or log. The UUID v7 variant leaks creation time anywhere the Id is
+ * copied (logs, URLs, exports); only use it when you explicitly want insertion
+ * locality for very large write‑heavy tables and accept timestamp exposure.
+ *
+ * ### Future
+ *
+ * A possible hybrid masked‑time approach (`timestamp ^ H(cluster_id, timestamp
+ *
+ * > > N)`) could provide locality without exposing raw creation time. See
+ * > > https://brooker.co.za/blog/2025/10/22/uuidv7.html
  *
  * @category String
  */
@@ -1599,26 +1628,25 @@ export const formatIdError = createTypeErrorFormatter<IdError>(
 );
 
 /**
- * Creates an {@link Id}.
+ * Creates a random {@link Id}. This is the recommended default.
+ *
+ * Use {@link createIdFromString} for deterministic mapping of external IDs or
+ * {@link createIdAsUuidv7} when you accept timestamp leakage for index
+ * locality.
  *
  * ### Example
  *
  * ```ts
- * // string & Brand<"Id">
  * const id = createId(deps);
- *
- * // string & Brand<"Id"> & Brand<"Todo">
  * const todoId = createId<"Todo">(deps);
  * ```
  */
 export const createId = <B extends string = never>(
   deps: RandomBytesDep,
-): [B] extends [never] ? Id : Id & Brand<B> =>
-  uint8ArrayToBase64Url(deps.randomBytes.create(16)) as unknown as [B] extends [
-    never,
-  ]
-    ? Id
-    : Id & Brand<B>;
+): [B] extends [never] ? Id : Id & Brand<B> => {
+  const id = uint8ArrayToBase64Url(deps.randomBytes.create(16));
+  return id as unknown as [B] extends [never] ? Id : Id & Brand<B>;
+};
 
 /**
  * Creates an {@link Id} from a string using SHA-256.
@@ -1662,6 +1690,42 @@ export const createIdFromString = <B extends string = never>(
   return id as [B] extends [never] ? Id : Id & Brand<B>;
 };
 
+/**
+ * Creates an {@link Id} embedding timestamp bits (UUID v7 layout) before
+ * Base64Url encoding.
+ *
+ * Tradeoff: better insertion locality / index performance for huge datasets vs
+ * leaking creation time everywhere the Id appears. Evolu uses {@link createId}
+ * by default to avoid activity leakage; choose this only if you explicitly
+ * accept timestamp exposure.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const id = createIdAsUuidv7({ randomBytes, time });
+ * const todoId = createIdAsUuidv7<"Todo">({ randomBytes, time });
+ * ```
+ */
+export const createIdAsUuidv7 = <B extends string = never>(
+  deps: RandomBytesDep & TimeDep,
+): [B] extends [never] ? Id : Id & Brand<B> => {
+  const id = deps.randomBytes.create(16);
+
+  const timestamp = globalThis.BigInt(deps.time.now());
+
+  id[0] = globalThis.Number((timestamp >> 40n) & 0xffn);
+  id[1] = globalThis.Number((timestamp >> 32n) & 0xffn);
+  id[2] = globalThis.Number((timestamp >> 24n) & 0xffn);
+  id[3] = globalThis.Number((timestamp >> 16n) & 0xffn);
+  id[4] = globalThis.Number((timestamp >> 8n) & 0xffn);
+  id[5] = globalThis.Number(timestamp & 0xffn);
+
+  id[6] = (id[6] & 0x0f) | 0x70;
+  id[8] = (id[8] & 0x3f) | 0x80;
+
+  return id as unknown as [B] extends [never] ? Id : Id & Brand<B>;
+};
+
 /**
  * Creates a branded {@link Id} Type for a table's primary key.
  *
@@ -3432,26 +3496,6 @@ export const formatInt64Error = createTypeErrorFormatter<Int64Error>(
     `The value ${error.value} is not a valid 64-bit signed integer (Int64).`,
 );
 
-// // co s timhle? je to string, ze ktereho lze udelat bigint
-
-// export const BigIntFromString = transform(
-//   String,
-//   BigInt,
-//   (value) =>
-//     trySync(
-//       () => globalThis.BigInt(value),
-//       (): BigIntFromStringError => ({ type: "BigIntFromString", value }),
-//     ),
-//   (value) => value.toString(),
-// );
-
-// export interface BigIntFromStringError extends TypeError<"BigIntFromString"> {}
-
-// export const formatBigIntFromStringError =
-//   createTypeErrorFormatter<BigIntFromStringError>(
-//     (error) => `The value ${error.value} could not be converted to a BigInt.`,
-//   );
-
 /**
  * Stringified {@link Int64}.
  *