Improve objectToEntries type safety and docs

Updated objectToEntries to return ReadonlyArray for better immutability guarantees and improved the documentation with a clearer example and explanation of branded key preservation.

Author: steida

packages/common/src/Evolu/Query.ts

@@ -1,3 +1,4 @@
+import { Brand } from "../Brand.js";
 import { bytesToHex, hexToBytes } from "../Buffer.js";
 import { objectToEntries } from "../Object.js";
 import {
@@ -9,7 +10,6 @@ import {
 } from "../Sqlite.js";
 import { Store, StoreSubscribe } from "../Store.js";
 import { Simplify } from "../Types.js";
-import { Brand } from "../Brand.js";
 
 /**
  * A type-safe SQL query.
@@ -52,7 +52,7 @@ export const serializeQuery = <R extends Row>(query: SqliteQuery): Query<R> => {
   );
 
   const options = query.options
-    ? objectToEntries(query.options).sort(([a], [b]) => a.localeCompare(b))
+    ? objectToEntries(query.options).toSorted(([a], [b]) => a.localeCompare(b))
     : [];
 
   return JSON.stringify([query.sql, params, options]) as Query<R>;

packages/common/src/Object.ts

@@ -25,14 +25,22 @@ export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
 type StringKeyOf<T> = Extract<keyof T, string>;
 
 /**
- * Converts a record to entries, preserving branded string key types (e.g.,
- * `type Id = 'id' & string`) via `StringKeyOf<T>`, unlike `Object.entries`
- * which widens keys to `string`.
+ * Like `Object.entries` but preserves branded keys.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type UserId = string & { readonly __brand: "UserId" };
+ * const users: Record<UserId, string> = {};
+ * const entries = objectToEntries(users); // [UserId, string][]
+ * ```
  */
 export const objectToEntries = <T extends Record<string, any>>(
   record: T,
-): Array<[StringKeyOf<T>, T[StringKeyOf<T>]]> =>
-  Object.entries(record) as Array<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
+): ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]> =>
+  Object.entries(record) as Array<
+    [StringKeyOf<T>, T[StringKeyOf<T>]]
+  > as ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
 
 /**
  * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving