Merge pull request evoluhq#644 from evoluhq/refactoring

Refactoring

Author: steida

.changeset/beige-sloths-lead.md

@@ -0,0 +1,12 @@
+---
+"@evolu/common": minor
+---
+
+Added `getProperty` helper function
+
+Safely gets a property from a record, returning `undefined` if the key doesn't exist. TypeScript's `Record<K, V>` type assumes all keys exist, but at runtime accessing a non-existent key returns `undefined`. This helper provides proper typing for that case without needing a type assertion.
+
+```ts
+const users: Record<string, User> = { alice: { name: "Alice" } };
+const user = getProperty(users, "bob"); // User | undefined
+```

.changeset/honest-cars-draw.md

@@ -0,0 +1,14 @@
+---
+"@evolu/common": minor
+---
+
+Added `set` Type factory
+
+The `set` factory creates a Type for validating `Set` instances with typed elements. It validates that the input is a `Set` and that all elements conform to the specified element type.
+
+```ts
+const NumberSet = set(Number);
+
+const result1 = NumberSet.from(new Set([1, 2, 3])); // ok(Set { 1, 2, 3 })
+const result2 = NumberSet.from(new Set(["a", "b"])); // err(...)
+```

.changeset/humble-meals-wish.md

@@ -0,0 +1,7 @@
+---
+"@evolu/common": minor
+---
+
+Added `readonly` helper function
+
+The `readonly` function casts arrays, sets, records, and maps to their readonly counterparts with zero runtime cost. It preserves `NonEmptyArray` as `NonEmptyReadonlyArray` and provides proper type inference for all supported collection types.

.changeset/silver-jars-smell.md

@@ -0,0 +1,24 @@
+---
+"@evolu/common": patch
+---
+
+Update Result documentation with block scope pattern for multiple void operations
+
+```ts
+// Before - inventing names to avoid name clash
+const baseTables = createBaseSqliteStorageTables(deps);
+if (!baseTables.ok) return baseTables;
+
+const relayTables = createRelayStorageTables(deps);
+if (!relayTables.ok) return relayTables;
+
+// After - block scopes avoid name clash
+{
+  const result = createBaseSqliteStorageTables(deps);
+  if (!result.ok) return result;
+}
+{
+  const result = createRelayStorageTables(deps);
+  if (!result.ok) return result;
+}
+```

.changeset/three-buses-play.md

@@ -0,0 +1,7 @@
+---
+"@evolu/common": patch
+---
+
+Fix forward compatibility by quarantining messages with unknown schema
+
+Messages with unknown tables or columns are now stored in `evolu_message_quarantine` table instead of being discarded. This fixes an issue where apps had to be updated to receive messages from newer versions. The quarantine table is queryable via `createQuery` and quarantined messages are automatically applied when the schema is updated.

.github/copilot-instructions.md

@@ -72,6 +72,24 @@ export const createUser = (data: UserData): User => {
 };
 ````
 
+## API stability & experimental APIs
+
+- **Use `@experimental` tag** for new APIs that may change or be removed
+- **Experimental APIs can change** in minor/patch versions without breaking semver
+- **Promote to stable** once confident in the design after real-world usage
+
+```ts
+// ✅ Good - Mark new/uncertain APIs as experimental
+/**
+ * Casts a value to its readonly counterpart.
+ *
+ * @experimental
+ */
+export const readonly = <T>(value: T): Readonly<T> => value;
+```
+
+This pattern allows iterating on API design without committing to stability too early.
+
 ## Error handling with Result
 
 - Use `Result<T, E>` for business/domain errors in public APIs
@@ -94,13 +112,10 @@ const parseJson = (value: string): Result<unknown, ParseJsonError> =>
 
 // ✅ Good - Sequential operations with short-circuiting
 const processData = (deps: DataDeps) => {
-  const step1Result = doStep1(deps);
-  if (!step1Result.ok) return step1Result;
-
-  const step2Result = doStep2(deps)(step1Result.value);
-  if (!step2Result.ok) return step2Result;
+  const foo = doFoo(deps);
+  if (!foo.ok) return foo;
 
-  return ok(step2Result.value);
+  return doStep2(deps)(foo.value);
 };
 
 // ❌ Avoid - Implementation error in public API

apps/web/src/app/(docs)/docs/conventions/page.mdx

@@ -66,9 +66,16 @@ const bar = () => {
 
 ## Immutability
 
-Mutable state can be tricky because it increases the risk of unintended side effects, makes code harder to predict, and complicates debugging—especially in complex applications where data might be shared or modified unexpectedly.
+Mutable state is tricky because it increases the risk of unintended side effects, makes code harder to predict, and complicates debugging—especially in complex applications where data might be shared or modified unexpectedly. Favor immutable values using readonly types to reduce these risks and improve clarity.
 
-Favor immutable values using TypeScript's type system to reduce these risks and improve clarity. Use `ReadonlyArray` and `NonEmptyReadonlyArray` for arrays and prefix interface properties with readonly to enforce immutability at the type level.
+### Readonly types
+
+Use readonly types for collections and prefix interface properties with `readonly`:
+
+- `ReadonlyArray<T>` and `NonEmptyReadonlyArray<T>` for arrays
+- `ReadonlySet<T>` for sets
+- `ReadonlyRecord<K, V>` for records
+- `ReadonlyMap<K, V>` for maps
 
 ```ts
 // Use ReadonlyArray for immutable arrays.
@@ -78,9 +85,47 @@ const values: ReadonlyArray<string> = ["a", "b", "c"];
 interface Example {
   readonly id: number;
   readonly items: ReadonlyArray<string>;
+  readonly tags: ReadonlySet<string>;
 }
 ```
 
+### The `readonly` helper
+
+Use the [readonly](/docs/api-reference/common/Function/functions/readonly) helper to cast arrays, sets, records, and maps to their readonly counterparts with zero runtime cost.
+
+```ts
+import { readonly, NonEmptyArray } from "@evolu/common";
+
+// Array literals become NonEmptyReadonlyArray
+const items = readonly([1, 2, 3]);
+// Type: NonEmptyReadonlyArray<number>
+
+// NonEmptyArray is preserved as NonEmptyReadonlyArray
+const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
+const readonlyNonEmpty = readonly(nonEmpty);
+// Type: NonEmptyReadonlyArray<number>
+
+// Regular arrays become ReadonlyArray
+const arr: Array<number> = getNumbers();
+const readonlyArr = readonly(arr);
+// Type: ReadonlyArray<number>
+
+// Sets, Records, and Maps
+const ids = readonly(new Set(["a", "b"]));
+// Type: ReadonlySet<string>
+
+const users: Record<UserId, string> = { ... };
+const readonlyUsers = readonly(users);
+// Type: ReadonlyRecord<UserId, string>
+
+const lookup = readonly(new Map([["key", "value"]]));
+// Type: ReadonlyMap<string, string>
+```
+
+### Immutable helpers
+
+Evolu provides helpers in the [Array](/docs/api-reference/common/Array) and [Object](/docs/api-reference/common/Object) modules that do not mutate and preserve readonly types.
+
 ## Interface over type
 
 Prefer `interface` over `type` because interfaces always appear by name in error messages and tooltips.

eslint.config.mjs

@@ -46,6 +46,10 @@ export default defineConfig(
       "@typescript-eslint/explicit-module-boundary-types": "error",
       // https://github.com/typescript-eslint/typescript-eslint/issues/8113#issuecomment-2334943836
       "@typescript-eslint/no-invalid-void-type": "off",
+
+      // It seems its buggy, disable it for now.
+      "@typescript-eslint/no-redundant-type-constituents": "off",
+
       "@typescript-eslint/no-empty-object-type": "off",
       "@typescript-eslint/restrict-template-expressions": "off",
       "@typescript-eslint/no-unused-vars": [

packages/common/src/Function.ts

@@ -1,3 +1,6 @@
+import { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.js";
+import { ReadonlyRecord } from "./Object.js";
+
 /**
  * Helper function to ensure exhaustive matching in a switch statement. Throws
  * an error if an unhandled case is encountered.
@@ -31,8 +34,79 @@ export const exhaustiveCheck = (value: never): never => {
   throw new Error(`exhaustiveCheck unhandled case: ${JSON.stringify(value)}`);
 };
 
+/**
+ * Returns the input value unchanged.
+ *
+ * Useful as a default transformation, placeholder callback, or when a function
+ * is required but no transformation is needed.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const values = [1, 2, 3];
+ * const same = values.map(identity); // [1, 2, 3]
+ *
+ * const getTransform = (shouldDouble: boolean) =>
+ *   shouldDouble ? (x: number) => x * 2 : identity;
+ * ```
+ */
 export const identity = <A>(a: A): A => a;
 
+/**
+ * Casts an array, set, record, or map to its readonly counterpart.
+ *
+ * Zero runtime cost — returns the same value with a readonly type. Use this to
+ * enforce immutability at the type level. Preserves {@link NonEmptyArray} as
+ * {@link NonEmptyReadonlyArray}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Array literals become NonEmptyReadonlyArray
+ * const items = readonly([1, 2, 3]);
+ * // Type: NonEmptyReadonlyArray<number>
+ *
+ * // NonEmptyArray is preserved as NonEmptyReadonlyArray
+ * const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
+ * const readonlyNonEmpty = readonly(nonEmpty);
+ * // Type: NonEmptyReadonlyArray<number>
+ *
+ * // Regular arrays become ReadonlyArray
+ * const arr: Array<number> = getNumbers();
+ * const readonlyArr = readonly(arr);
+ * // Type: ReadonlyArray<number>
+ *
+ * // Sets, Records, and Maps
+ * const ids = readonly(new Set(["a", "b"]));
+ * // Type: ReadonlySet<string>
+ *
+ * const users: Record<UserId, string> = { ... };
+ * const readonlyUsers = readonly(users);
+ * // Type: ReadonlyRecord<UserId, string>
+ *
+ * const lookup = readonly(new Map([["key", "value"]]));
+ * // Type: ReadonlyMap<string, string>
+ * ```
+ *
+ * @experimental
+ */
+export function readonly<T>(array: NonEmptyArray<T>): NonEmptyReadonlyArray<T>;
+export function readonly<T>(array: Array<T>): ReadonlyArray<T>;
+export function readonly<T>(set: Set<T>): ReadonlySet<T>;
+export function readonly<K, V>(map: Map<K, V>): ReadonlyMap<K, V>;
+export function readonly<K extends keyof any, V>(
+  record: Record<K, V>,
+): ReadonlyRecord<K, V>;
+export function readonly<T, K extends keyof any, V>(
+  value: Array<T> | Set<T> | Map<K, V> | Record<K, V>,
+):
+  | ReadonlyArray<T>
+  | ReadonlySet<T>
+  | ReadonlyMap<K, V>
+  | ReadonlyRecord<K, V> {
+  return value;
+}
+
 /**
  * A function that delays computation and returns a value of type T.
  *

packages/common/src/Object.ts

@@ -89,3 +89,23 @@ export const createRecord = <K extends string = string, V = unknown>(): Record<
   K,
   V
 > => Object.create(null) as Record<K, V>;
+
+/**
+ * Safely gets a property from a record, returning `undefined` if the key
+ * doesn't exist.
+ *
+ * TypeScript's `Record<K, V>` type assumes all keys exist, but at runtime
+ * accessing a non-existent key returns `undefined`. This helper provides proper
+ * typing for that case without needing a type assertion.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const users: Record<string, User> = { alice: { name: "Alice" } };
+ * const user = getProperty(users, "bob"); // User | undefined
+ * ```
+ */
+export const getProperty = <K extends string, V>(
+  record: ReadonlyRecord<K, V>,
+  key: string,
+): V | undefined => (key in record ? record[key as K] : undefined);