@evolu/common 6.0.1-preview.32 → 6.0.1-preview.34

package/src/Array.ts

@@ -1,44 +1,121 @@
 /**
- * 🔒 Immutable, type-safe array operations
+ * 🔒 Immutable, type-safe array helpers
  *
- * Helpers that preserve immutability through the type system. Native array
- * methods return mutable arrays even when called on readonly arrays. These
- * helpers ensure transformations return readonly types.
+ * Array types, guards, operations, transformations, accessors, and mutations.
  *
- * {@link NonEmptyArray} and {@link NonEmptyReadonlyArray} types represent arrays
- * with at least one element, eliminating runtime length checks and making
- * function requirements explicit.
+ * Prepared for TC39 Hack pipes:
+ *
+ * ```ts
+ * // Problem: nested functions can be hard to follow
+ * const result = firstInArray(
+ *   mapArray(dedupeArray(appendToArray(value, 2)), (x) => x * 2),
+ * );
+ *
+ * // Ideal solution: TC39 Hack pipes (when available)
+ * // const result = value
+ * //   |> appendToArray(%, 2)
+ * //   |> dedupeArray(%)
+ * //   |> mapArray(%, (x) => x * 2)
+ * //   |> firstInArray(%);
+ *
+ * // Current solution: name each step (or use p1, p2 if lazy)
+ * const p1 = appendToArray(value, 2);
+ * const p2 = dedupeArray(p1);
+ * const p3 = mapArray(p2, (x) => x * 2);
+ * const p4 = firstInArray(p3);
+ * ```
+ *
+ * Of course it's possible to use array instance methods, but they mutate and do
+ * not preserve {@link NonEmptyArray} and {@link NonEmptyReadonlyArray} types.
  *
  * ### Example
  *
  * ```ts
- * // ❌ Native methods return mutable arrays
+ * // Types - compile-time guarantee of at least one element
+ * const _valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * // ts-expect-error - empty array is not a valid NonEmptyReadonlyArray
+ * const _invalid: NonEmptyReadonlyArray<number> = [];
+ *
+ * // Guards
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr);
+ * }
+ *
+ * // Operations
+ * const appended = appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * const prepended = prependToArray([2, 3], 1); // [1, 2, 3]
+ *
+ * // Transformations
  * const readonly: ReadonlyArray<number> = [1, 2, 3];
- * const mapped = readonly.map((x) => x * 2); // Array<number> (mutable!)
+ * const mapped = mapArray(readonly, (x) => x * 2); // [2, 4, 6]
+ * const filtered = filterArray(readonly, (x) => x > 1); // [2, 3]
+ * const deduped = dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
  *
- * // ✅ Helpers preserve immutability
- * const filtered = filterArray(readonly, (x) => x > 1); // ReadonlyArray<number>
+ * // Accessors
+ * const first = firstInArray(["a", "b", "c"]); // "a"
+ * const last = lastInArray(["a", "b", "c"]); // "c"
  *
- * // ✅ NonEmptyArray enforces non-emptiness
- * const value = firstInArray(["a", "b"]); // "a"
- * firstInArray([]); // ❌ Compiler error
+ * // Mutations
+ * const mutable: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(mutable); // 1 (guaranteed to exist)
+ * mutable; // [2, 3]
  * ```
  *
  * @module
  */
 
-/** An array with at least one element. */
+/**
+ * An array with at least one element.
+ *
+ * @category Types
+ */
 export type NonEmptyArray<T> = [T, ...Array<T>];
 
-/** Checks if an array is non-empty. */
+/**
+ * A readonly array with at least one element.
+ *
+ * @category Types
+ */
+export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
+
+/**
+ * Checks if an array is non-empty and narrows its type to {@link NonEmptyArray}.
+ *
+ * Use `if (!isNonEmptyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: Array<number> = [1, 2, 3];
+ * if (isNonEmptyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
 export const isNonEmptyArray = <T>(
   array: Array<T>,
 ): array is NonEmptyArray<T> => array.length > 0;
 
-/** A readonly array with at least one element. */
-export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
-
-/** Checks if an array is non-empty. */
+/**
+ * Checks if a readonly array is non-empty and narrows its type to
+ * {@link NonEmptyReadonlyArray}.
+ *
+ * Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyReadonlyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
 export const isNonEmptyReadonlyArray = <T>(
   array: ReadonlyArray<T>,
 ): array is NonEmptyReadonlyArray<T> => array.length > 0;
@@ -47,10 +124,18 @@ export const isNonEmptyReadonlyArray = <T>(
  * Appends an item to an array, returning a new non-empty readonly array.
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * ```
+ *
+ * @category Operations
  */
 export const appendToArray = <T>(
-  item: T,
   array: ReadonlyArray<T>,
+  item: T,
 ): NonEmptyReadonlyArray<T> =>
   [...array, item] as ReadonlyArray<T> as NonEmptyReadonlyArray<T>;
 
@@ -58,17 +143,33 @@ export const appendToArray = <T>(
  * Prepends an item to an array, returning a new non-empty readonly array.
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * prependToArray([2, 3], 1); // [1, 2, 3]
+ * ```
+ *
+ * @category Operations
  */
 export const prependToArray = <T>(
-  item: T,
   array: ReadonlyArray<T>,
+  item: T,
 ): NonEmptyReadonlyArray<T> => [item, ...array] as NonEmptyReadonlyArray<T>;
 
 /**
- * Maps an array using a mapper function, preserving non-emptiness when
- * applicable.
+ * Maps an array using a mapper function.
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * Preserves non-empty type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
+ * ```
+ *
+ * @category Transformations
  */
 export function mapArray<T, U>(
   array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
@@ -89,6 +190,14 @@ export function mapArray<T, U>(
  * Filters an array using a predicate function, returning a new readonly array.
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
+ * ```
+ *
+ * @category Transformations
  */
 export const filterArray = <T>(
   array: ReadonlyArray<T>,
@@ -96,44 +205,45 @@ export const filterArray = <T>(
 ): ReadonlyArray<T> => array.filter(predicate) as ReadonlyArray<T>;
 
 /**
- * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ * Returns a new readonly array with duplicate items removed. If `by` is
+ * provided, it will be used to derive the key for uniqueness; otherwise values
+ * are used directly. Dedupes by reference equality of values (or extracted keys
+ * when `by` is used).
  *
- * **Mutates** the original array. Use only with mutable arrays.
- */
-export const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;
-
-/**
- * Returns the first element of a non-empty readonly array.
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * Preserves non-empty type.
  *
- * Does not mutate the original array.
- */
-export const firstInArray = <T>(array: NonEmptyReadonlyArray<T>): T => array[0];
-
-/**
- * Returns the last element of a non-empty readonly array.
+ * ### Example
  *
- * Does not mutate the original array.
- */
-export const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
-  array[array.length - 1];
-
-/**
- * Returns a new readonly array with duplicate items removed based on a key
- * extractor function. Preserves the first occurrence of each distinct key.
+ * ```ts
+ * // Dedupe primitives by value
+ * dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
- */
-
-/**
- * Deduplicates items in an array. If `by` is provided, it will be used to
- * derive the key for uniqueness; otherwise values are used directly.
+ * // Dedupe objects by property
+ * dedupeArray(
+ *   [
+ *     { id: 1, name: "Alice" },
+ *     { id: 2, name: "Bob" },
+ *     { id: 1, name: "Alice 2" },
+ *   ],
+ *   (item) => item.id,
+ * ); // [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
+ * ```
  *
- * Returns a new readonly array and does not mutate the input.
+ * @category Transformations
  */
-export const dedupeArray = <T>(
+export function dedupeArray<T>(
+  array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>,
+  by?: (item: T) => unknown,
+): NonEmptyReadonlyArray<T>;
+export function dedupeArray<T>(
+  array: ReadonlyArray<T> | Array<T>,
+  by?: (item: T) => unknown,
+): ReadonlyArray<T>;
+export function dedupeArray<T>(
   array: ReadonlyArray<T>,
   by?: (item: T) => unknown,
-): ReadonlyArray<T> => {
+): ReadonlyArray<T> {
   if (by == null) {
     return Array.from(new Set(array)) as ReadonlyArray<T>;
   }
@@ -145,4 +255,52 @@ export const dedupeArray = <T>(
     seen.add(key);
     return true;
   }) as ReadonlyArray<T>;
-};
+}
+
+/**
+ * Returns the first element of a non-empty array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * firstInArray(["a", "b", "c"]); // "a"
+ * ```
+ *
+ * @category Accessors
+ */
+export const firstInArray = <T>(array: NonEmptyReadonlyArray<T>): T => array[0];
+
+/**
+ * Returns the last element of a non-empty array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * lastInArray(["a", "b", "c"]); // "c"
+ * ```
+ *
+ * @category Accessors
+ */
+export const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
+  array[array.length - 1];
+
+/**
+ * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(arr); // 1
+ * arr; // [2, 3]
+ * ```
+ *
+ * @category Mutations
+ */
+export const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;

package/src/Crypto.ts

@@ -172,10 +172,13 @@ export const createSymmetricCrypto = (
  * Returns the PADMÉ padded length for a given input length.
  *
  * PADMÉ limits information leakage about the length of the plain-text for a
- * wide range of encrypted data sizes. See the PURBs paper for details:
- * https://bford.info/pub/sec/purb.pdf
+ * wide range of encrypted data sizes.
+ *
+ * See the PURBs paper for details: https://bford.info/pub/sec/purb.pdf
  */
-export const padmePaddedLength = (length: NonNegativeInt): NonNegativeInt => {
+export const createPadmePaddedLength = (
+  length: NonNegativeInt,
+): NonNegativeInt => {
   if (length <= 0) return NonNegativeInt.orThrow(0);
   const e = 31 - Math.clz32(length >>> 0);
   const s = 32 - Math.clz32(e >>> 0);
@@ -184,12 +187,11 @@ export const padmePaddedLength = (length: NonNegativeInt): NonNegativeInt => {
   return NonNegativeInt.orThrow((length + mask) & ~mask);
 };
 
-/**
- * Returns the PADMÉ padding length for a given input length. Uses
- * {@link padmePaddedLength}.
- */
-export const padmePaddingLength = (length: NonNegativeInt): NonNegativeInt => {
-  return NonNegativeInt.orThrow(padmePaddedLength(length) - length);
+/** Creates a PADMÉ padding array of zeros for the given input length. */
+export const createPadmePadding = (length: NonNegativeInt): Uint8Array => {
+  const paddedLength = createPadmePaddedLength(length);
+  const paddingLength = NonNegativeInt.orThrow(paddedLength - length);
+  return new globalThis.Uint8Array(paddingLength);
 };
 
 /**

package/src/Evolu/Db.ts

@@ -63,11 +63,11 @@ import {
 } from "./Sync.js";
 import {
   Timestamp,
+  TimestampBytes,
+  timestampBytesToTimestamp,
   TimestampConfig,
   TimestampError,
-  TimestampString,
-  timestampStringToTimestamp,
-  timestampToTimestampString,
+  timestampToTimestampBytes,
 } from "./Timestamp.js";
 
 export interface DbConfig extends ConsoleConfig, TimestampConfig {
@@ -387,7 +387,7 @@ const createDbWorkerDeps =
         // }
 
         const configResult = sqlite.exec<{
-          clock: TimestampString;
+          clock: TimestampBytes;
           appOwnerId: OwnerId;
           appOwnerEncryptionKey: OwnerEncryptionKey;
           appOwnerWriteKey: OwnerWriteKey;
@@ -415,7 +415,7 @@ const createDbWorkerDeps =
         };
 
         clock = createClock({ ...platformDeps, sqlite })(
-          timestampStringToTimestamp(config.clock),
+          timestampBytesToTimestamp(config.clock),
         );
       } else {
         appOwner =
@@ -507,7 +507,7 @@ const initializeDb =
 
       sql`
         create table evolu_config (
-          "clock" text not null,
+          "clock" blob not null,
           "appOwnerId" text not null,
           "appOwnerEncryptionKey" blob not null,
           "appOwnerWriteKey" blob not null,
@@ -527,7 +527,7 @@ const initializeDb =
           )
         values
           (
-            ${timestampToTimestampString(initialClock)},
+            ${timestampToTimestampBytes(initialClock)},
             ${initialAppOwner.id},
             ${initialAppOwner.encryptionKey},
             ${initialAppOwner.writeKey},

package/src/Evolu/Evolu.ts

@@ -4,7 +4,7 @@ import {
   isNonEmptyArray,
   isNonEmptyReadonlyArray,
 } from "../Array.js";
-import { assert, assertNonEmptyReadonlyArray } from "../Assert.js";
+import { assertNonEmptyReadonlyArray } from "../Assert.js";
 import { createCallbacks } from "../Callbacks.js";
 import { ConsoleDep } from "../Console.js";
 import { RandomBytesDep, SymmetricCryptoDecryptError } from "../Crypto.js";
@@ -48,7 +48,6 @@ import {
 } from "./Query.js";
 import {
   CreateQuery,
-  DefaultColumns,
   EvoluSchema,
   evoluSchemaToDbSchema,
   IndexesConfig,
@@ -59,6 +58,7 @@ import {
   MutationKind,
   MutationMapping,
   MutationOptions,
+  SystemColumns,
   updateable,
   upsertable,
   ValidateSchema,
@@ -239,7 +239,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
    *
    * Evolu does not use SQL for mutations to ensure data can be safely and
    * predictably merged without conflicts. Explicit mutations also allow Evolu
-   * to automatically add and update {@link DefaultColumns}.
+   * to automatically add and update {@link SystemColumns}.
    *
    * ### Example
    *
@@ -284,7 +284,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
    *
    * Evolu does not use SQL for mutations to ensure data can be safely and
    * predictably merged without conflicts. Explicit mutations also allow Evolu
-   * to automatically add and update {@link DefaultColumns}.
+   * to automatically add and update {@link SystemColumns}.
    *
    * ### Example
    *
@@ -337,7 +337,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
    *
    * Evolu does not use SQL for mutations to ensure data can be safely and
    * predictably merged without conflicts. Explicit mutations also allow Evolu
-   * to automatically add and update {@link DefaultColumns}.
+   * to automatically add and update {@link SystemColumns}.
    *
    * ### Example
    *
@@ -408,7 +408,12 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
    */
   readonly reloadApp: () => void;
 
-  /** Export SQLite database file as Uint8Array. */
+  /**
+   * Export SQLite database file as Uint8Array.
+   *
+   * In the future, it will be possible to import a database and export/import
+   * history for 1:1 migrations across owners.
+   */
   readonly exportDatabase: () => Promise<Uint8Array<ArrayBuffer>>;
 
   /**
@@ -716,21 +721,17 @@ const createEvoluInstance =
             const values = { ...result.value };
             delete values.id;
 
-            if (kind === "insert" || kind === "upsert") {
-              // Only set createdAt if not provided by user
-              if (!("createdAt" in values)) {
-                values.createdAt = new Date(deps.time.now()).toISOString();
-              }
-            }
-
-            const dbChange = { table, id, values };
-            assert(
-              DbChange.is(dbChange),
-              `Failed to create DbChange for table "${dbChange.table}"`,
-            );
+            const dbChange = DbChange.orThrow({
+              table,
+              id,
+              values,
+              isInsert: kind === "insert" || kind === "upsert",
+            });
 
-            const mutationChange = { ...dbChange, ownerId: options?.ownerId };
-            mutateMicrotaskQueue.push([mutationChange, options?.onComplete]);
+            mutateMicrotaskQueue.push([
+              { ...dbChange, ownerId: options?.ownerId },
+              options?.onComplete,
+            ]);
           }
 
           if (mutateMicrotaskQueue.length === 1) {