atom.io 0.44.15 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atom.io",
-  "version": "0.44.15",
+  "version": "0.45.0",
   "description": "Composable and testable reactive data library.",
   "homepage": "https://atom.io.fyi",
   "sideEffects": false,
@@ -72,7 +72,7 @@
     "@typescript-eslint/parser": "8.47.0",
     "@typescript-eslint/rule-tester": "8.47.0",
     "@typescript-eslint/utils": "8.47.0",
-    "@typescript/native-preview": "7.0.0-dev.20251129.1",
+    "@typescript/native-preview": "7.0.0-dev.20251130.1",
     "@vitest/coverage-v8": "4.0.14",
     "@vitest/ui": "4.0.14",
     "arktype": "2.1.27",
@@ -111,10 +111,6 @@
       "import": "./dist/main/index.js",
       "types": "./dist/main/index.d.ts"
     },
-    "./data": {
-      "import": "./dist/data/index.js",
-      "types": "./dist/data/index.d.ts"
-    },
     "./eslint-plugin": {
       "import": "./dist/eslint-plugin/index.js",
       "types": "./dist/eslint-plugin/index.d.ts"
@@ -162,10 +158,6 @@
       "import": "./dist/realtime-testing/index.js",
       "types": "./dist/realtime-testing/index.d.ts"
     },
-    "./struct": {
-      "import": "./dist/struct/index.js",
-      "types": "./dist/struct/index.d.ts"
-    },
     "./transceivers/o-list": {
       "import": "./dist/transceivers/o-list/index.js",
       "types": "./dist/transceivers/o-list/index.d.ts"

package/src/introspection/attach-introspection-states.ts

@@ -22,7 +22,7 @@ export type IntrospectionStates = {
 	selectorIndex: AtomToken<SelectorTokenIndex>
 	transactionIndex: AtomToken<TransactionToken<Fn>[]>
 	transactionLogSelectors: ReadonlyPureSelectorFamilyToken<
-		TransactionOutcomeEvent<TransactionToken<Fn>>[],
+		readonly TransactionOutcomeEvent<TransactionToken<Fn>>[],
 		string
 	>
 	timelineIndex: AtomToken<TimelineToken<any>[]>

package/src/introspection/attach-transaction-logs.ts

@@ -9,7 +9,7 @@ import { createRegularAtomFamily, createSelectorFamily } from "atom.io/internal"
 export const attachTransactionLogs = (
 	store: RootStore,
 ): ReadonlyPureSelectorFamilyToken<
-	TransactionOutcomeEvent<TransactionToken<any>>[],
+	readonly TransactionOutcomeEvent<TransactionToken<any>>[],
 	string
 > => {
 	const transactionUpdateLogAtoms = createRegularAtomFamily<
@@ -31,7 +31,7 @@ export const attachTransactionLogs = (
 		],
 	})
 	const findTransactionUpdateLogState = createSelectorFamily<
-		TransactionOutcomeEvent<TransactionToken<any>>[],
+		readonly TransactionOutcomeEvent<TransactionToken<any>>[],
 		string,
 		never
 	>(store, {

package/src/introspection/index.ts

@@ -11,5 +11,8 @@ export type FamilyNode<Token extends ReadableToken<unknown, any, any>> = {
 	familyMembers: Map<string, Token>
 }
 
+export type ReadonlyTokenIndex<Token extends ReadableToken<unknown, any, any>> =
+	ReadonlyMap<string, FamilyNode<Token> | Token>
+
 export type WritableTokenIndex<Token extends ReadableToken<unknown, any, any>> =
 	Map<string, FamilyNode<Token> | Token>

package/src/json/canonical.ts

@@ -0,0 +1,42 @@
+import type { primitive } from "./json"
+
+/** Only Canonical values should be used for keys because they always serialize to the same string */
+export type Canonical = primitive | ReadonlyArray<Canonical>
+
+export type packed<C extends Canonical> = string & { __canonical?: C }
+
+const BOOL = `\u0001`
+const NULL = `\u0002`
+const STRING = `\u0003`
+const NUMBER = `\u0004`
+export const packCanonical = <C extends Canonical>(
+	value: Canonical,
+): packed<C> => {
+	if (value === null) return NULL
+	// eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
+	switch (typeof value) {
+		case `string`:
+			return STRING + value
+		case `number`:
+			return NUMBER + value
+		case `boolean`:
+			return BOOL + +value
+		case `object`: // array
+			return JSON.stringify(value)
+	}
+}
+export const unpackCanonical = <C extends Canonical>(value: packed<C>): C => {
+	const type = value[0] as `[` | `\u0001` | `\u0002` | `\u0003` | `\u0004`
+	switch (type) {
+		case STRING:
+			return value.slice(1) as C
+		case NUMBER:
+			return +value.slice(1) as C
+		case BOOL:
+			return (value.slice(1) === `1`) as C
+		case NULL:
+			return null as C
+		case `[`:
+			return JSON.parse(value)
+	}
+}

package/src/json/enumeration.ts

@@ -0,0 +1,36 @@
+import type { Flat } from "atom.io/internal"
+
+export type IndexOf<
+	T extends readonly unknown[],
+	E,
+	A extends unknown[] = [],
+> = T extends readonly [infer Head, ...infer Tail]
+	? (<U>() => U extends Head ? 1 : 2) extends <U>() => U extends E ? 1 : 2
+		? A[`length`]
+		: IndexOf<Tail, E, [...A, unknown]>
+	: never
+
+export type Flip<T extends Record<string, number | string>> = {
+	[K in keyof T as T[K]]: K
+}
+
+export type TwoWay<T extends Record<string, number | string>> = Flip<T> & T
+
+export type Enumeration<T extends readonly string[]> = Flat<
+	TwoWay<{
+		[K in T[number]]: IndexOf<T, K>
+	}>
+>
+
+export function enumeration<T extends readonly string[]>(
+	values: T,
+): Enumeration<T> {
+	const result: Record<any, any> = {}
+	let i = 0
+	for (const value of values) {
+		result[value] = i
+		result[i] = value
+		++i
+	}
+	return result as Enumeration<T>
+}

package/src/json/index.ts

@@ -1,133 +1,4 @@
-import type { ViewOf } from "atom.io"
-
+export * from "./canonical"
 export * from "./entries"
-
-export type primitive = boolean | number | string | null
-
-export namespace Json {
-	export namespace Tree {
-		// eslint-disable-next-line @typescript-eslint/no-shadow
-		export type Array<Element = unknown> = ReadonlyArray<Element>
-		// eslint-disable-next-line @typescript-eslint/no-shadow
-		export type Object<K extends string = string, V = unknown> = Record<K, V>
-		export type Fork = Array | Object
-		export type Leaf = primitive
-		export type Node = Fork | Leaf
-	}
-
-	/** A value can survive being {@link JSON.stringify}-ed and {@link JSON.parse}-d fully intact */
-	export type Serializable =
-		| primitive
-		| Readonly<{ [key: string]: Serializable }>
-		| ReadonlyArray<Serializable>
-
-	export type Object<
-		Key extends string = string,
-		Value extends Serializable = Serializable,
-	> = Record<Key, Value>
-
-	export type Array<Element extends Serializable = Serializable> =
-		ReadonlyArray<Element>
-}
-
-/** A generic that retains the type information of a {@link Json.Serializable} value while in string form */
-// biome-ignore format: long silly ternary
-export type stringified<J extends Json.Serializable> = (
-      J extends string
-    ? `"${J}"`
-    : J extends number
-    ? `${J}`
-    : J extends true
-    ? `true`
-    : J extends false
-    ? `false`
-    : J extends boolean
-    ? `false` | `true`
-    : J extends null
-    ? `null`
-    : J extends []
-    ? `[]`
-    : J extends [infer Element extends Json.Serializable]
-    ? `[${stringified<Element>}]`
-    : J extends [
-					infer Element1 extends Json.Serializable,
-					infer Element2 extends Json.Serializable,
-				]
-    ? `[${stringified<Element1>}, ${stringified<Element2>}]`
-    : J extends [
-					infer Element1 extends Json.Serializable,
-					infer Element2 extends Json.Serializable,
-					infer Element3 extends Json.Serializable,
-				]
-    ? `[${stringified<Element1>}, ${stringified<Element2>}, ${stringified<Element3>}]`
-    : J extends any[]
-    ? `[${string}]` & { __json?: J }
-    : string & { __json?: J }
-  )
-
-/** Type-safe wrapper for {@link JSON.parse} */
-export function parseJson<J extends Json.Serializable>(str: stringified<J>): J
-/** Type-safe wrapper for {@link JSON.parse} */
-export function parseJson(str: string): Json.Serializable
-export function parseJson(str: string): Json.Serializable {
-	return JSON.parse(str)
-}
-
-/** Type-safe wrapper for {@link JSON.stringify} */
-export const stringifyJson = <J extends Json.Serializable>(
-	json: J,
-): stringified<J> => JSON.stringify(json) as stringified<J>
-
-/** Only Canonical values should be used for keys because they always serialize to the same string */
-export type Canonical = primitive | ReadonlyArray<Canonical>
-
-/** A function whose parameters and return value are {@link Json.Serializable} */
-export type JsonIO = (...params: Json.Serializable[]) => Json.Serializable | void
-
-export type JsonInterface<T, J extends Json.Serializable = Json.Serializable> = {
-	toJson: (t: ViewOf<T>) => J
-	fromJson: (json: J) => T
-}
-
-const JSON_PROTOTYPES = [
-	Array.prototype,
-	Boolean.prototype,
-	Number.prototype,
-	Object.prototype,
-	String.prototype,
-] as const
-export const isJson = (input: unknown): input is Json.Tree.Node => {
-	if (input === null) return true
-	if (input === undefined) return false
-	const prototype = Object.getPrototypeOf(input)
-	return JSON_PROTOTYPES.includes(prototype)
-}
-
-export const JSON_TYPE_NAMES = [
-	`array`,
-	`boolean`,
-	`null`,
-	`number`,
-	`object`,
-	`string`,
-] as const
-
-export type JsonTypeName = (typeof JSON_TYPE_NAMES)[number]
-
-export interface JsonTypes extends Record<JsonTypeName, Json.Serializable> {
-	array: Json.Array
-	boolean: boolean
-	null: null
-	number: number
-	object: Json.Object
-	string: string
-}
-
-export const JSON_DEFAULTS: JsonTypes = {
-	array: [],
-	boolean: false,
-	null: null,
-	number: 0,
-	object: {},
-	string: ``,
-}
+export * from "./enumeration"
+export * from "./json"

package/src/json/json.ts

@@ -0,0 +1,128 @@
+import type { ViewOf } from "atom.io"
+
+export type primitive = boolean | number | string | null
+
+export namespace Json {
+	export namespace Tree {
+		// eslint-disable-next-line @typescript-eslint/no-shadow
+		export type Array<Element = unknown> = ReadonlyArray<Element>
+		// eslint-disable-next-line @typescript-eslint/no-shadow
+		export type Object<K extends string = string, V = unknown> = Record<K, V>
+		export type Fork = Array | Object
+		export type Leaf = primitive
+		export type Node = Fork | Leaf
+	}
+
+	/** A value can survive being {@link JSON.stringify}-ed and {@link JSON.parse}-d fully intact */
+	export type Serializable =
+		| primitive
+		| Readonly<{ [key: string]: Serializable }>
+		| ReadonlyArray<Serializable>
+
+	export type Object<
+		Key extends string = string,
+		Value extends Serializable = Serializable,
+	> = Record<Key, Value>
+
+	export type Array<Element extends Serializable = Serializable> =
+		ReadonlyArray<Element>
+}
+
+/** A generic that retains the type information of a {@link Json.Serializable} value while in string form */
+// biome-ignore format: long silly ternary
+export type stringified<J extends Json.Serializable> = (
+      J extends string
+    ? `"${J}"`
+    : J extends number
+    ? `${J}`
+    : J extends true
+    ? `true`
+    : J extends false
+    ? `false`
+    : J extends boolean
+    ? `false` | `true`
+    : J extends null
+    ? `null`
+    : J extends []
+    ? `[]`
+    : J extends [infer Element extends Json.Serializable]
+    ? `[${stringified<Element>}]`
+    : J extends [
+					infer Element1 extends Json.Serializable,
+					infer Element2 extends Json.Serializable,
+				]
+    ? `[${stringified<Element1>}, ${stringified<Element2>}]`
+    : J extends [
+					infer Element1 extends Json.Serializable,
+					infer Element2 extends Json.Serializable,
+					infer Element3 extends Json.Serializable,
+				]
+    ? `[${stringified<Element1>}, ${stringified<Element2>}, ${stringified<Element3>}]`
+    : J extends any[]
+    ? `[${string}]` & { __json?: J }
+    : string & { __json?: J }
+  )
+
+/** Type-safe wrapper for {@link JSON.parse} */
+export function parseJson<J extends Json.Serializable>(str: stringified<J>): J
+/** Type-safe wrapper for {@link JSON.parse} */
+export function parseJson(str: string): Json.Serializable
+export function parseJson(str: string): Json.Serializable {
+	return JSON.parse(str)
+}
+
+/** Type-safe wrapper for {@link JSON.stringify} */
+export const stringifyJson = <J extends Json.Serializable>(
+	json: J,
+): stringified<J> => JSON.stringify(json) as stringified<J>
+
+/** A function whose parameters and return value are {@link Json.Serializable} */
+export type JsonIO = (...params: Json.Serializable[]) => Json.Serializable | void
+
+export type JsonInterface<T, J extends Json.Serializable = Json.Serializable> = {
+	toJson: (t: ViewOf<T>) => J
+	fromJson: (json: J) => T
+}
+
+const JSON_PROTOTYPES = [
+	Array.prototype,
+	Boolean.prototype,
+	Number.prototype,
+	Object.prototype,
+	String.prototype,
+] as const
+export const isJson = (input: unknown): input is Json.Tree.Node => {
+	if (input === null) return true
+	if (input === undefined) return false
+	const prototype = Object.getPrototypeOf(input)
+	return JSON_PROTOTYPES.includes(prototype)
+}
+
+export const JSON_TYPE_NAMES = [
+	`array`,
+	`boolean`,
+	`null`,
+	`number`,
+	`object`,
+	`string`,
+] as const
+
+export type JsonTypeName = (typeof JSON_TYPE_NAMES)[number]
+
+export interface JsonTypes extends Record<JsonTypeName, Json.Serializable> {
+	array: Json.Array
+	boolean: boolean
+	null: null
+	number: number
+	object: Json.Object
+	string: string
+}
+
+export const JSON_DEFAULTS: JsonTypes = {
+	array: [],
+	boolean: false,
+	null: null,
+	number: 0,
+	object: {},
+	string: ``,
+}

package/src/main/index.ts

@@ -15,7 +15,6 @@ export * from "./timeline"
 export type * from "./tokens"
 export * from "./transaction"
 export * from "./validators"
-
 /**
  * Loadable is used to type atoms or selectors that may at some point be initialized to or set to a {@link Promise}.
  *
@@ -25,4 +24,12 @@ export * from "./validators"
  */
 export type Loadable<T> = Promise<T> | T
 
-export type ViewOf<T> = T extends { READONLY_VIEW: infer View } ? View : T
+export type ViewOf<T> = T extends { READONLY_VIEW: infer View }
+	? View
+	: T extends Array<any>
+		? readonly [...T]
+		: T extends Set<infer U>
+			? ReadonlySet<ViewOf<U>>
+			: T extends Map<infer K, infer V>
+				? ReadonlyMap<ViewOf<K>, ViewOf<V>>
+				: T

package/src/react/use-loadable.ts

@@ -1,5 +1,10 @@
 /** biome-ignore-all lint/correctness/useHookAtTopLevel: params are used in an invariant way */
-import type { Loadable, ReadableFamilyToken, ReadableToken } from "atom.io"
+import type {
+	Loadable,
+	ReadableFamilyToken,
+	ReadableToken,
+	ViewOf,
+} from "atom.io"
 import { findInStore, type ReadableState, withdraw } from "atom.io/internal"
 import type { Canonical } from "atom.io/json"
 import { StoreContext, useO } from "atom.io/react"
@@ -7,23 +12,23 @@ import { useContext, useRef } from "react"
 
 export function useLoadable<T, E>(
 	token: ReadableToken<Loadable<T>, any, E>,
-): `LOADING` | { loading: boolean; value: E | T }
+): `LOADING` | { loading: boolean; value: ViewOf<E | T> }
 
 export function useLoadable<T, K extends Canonical, E>(
 	token: ReadableFamilyToken<Loadable<T>, K, E>,
 	key: NoInfer<K>,
-): `LOADING` | { loading: boolean; value: E | T }
+): `LOADING` | { loading: boolean; value: ViewOf<E | T> }
 
 export function useLoadable<T, F extends T, E>(
 	token: ReadableToken<Loadable<T>, any, E>,
 	fallback: F,
-): { loading: boolean; value: T; error?: E }
+): { loading: boolean; value: ViewOf<T>; error?: E }
 
 export function useLoadable<T, K extends Canonical, F extends T, E>(
 	token: ReadableFamilyToken<Loadable<T>, K, E>,
 	key: NoInfer<K>,
 	fallback: F,
-): { loading: boolean; value: T; error?: E }
+): { loading: boolean; value: ViewOf<T>; error?: E }
 
 export function useLoadable(
 	...params:

package/src/react-devtools/TransactionIndex.tsx

@@ -16,7 +16,7 @@ export const TransactionLog: FC<{
 	token: TransactionToken<Fn>
 	isOpenState: RegularAtomToken<boolean>
 	logState: ReadonlyPureSelectorToken<
-		TransactionOutcomeEvent<TransactionToken<Fn>>[]
+		readonly TransactionOutcomeEvent<TransactionToken<Fn>>[]
 	>
 }> = ({ token, isOpenState, logState }) => {
 	const log = useO(logState)

package/src/react-devtools/store.ts

@@ -13,7 +13,7 @@ import {
 } from "atom.io/internal"
 import type {
 	IntrospectionStates,
-	WritableTokenIndex,
+	ReadonlyTokenIndex,
 } from "atom.io/introspection"
 import { attachIntrospectionStates, isPlainObject } from "atom.io/introspection"
 import { storageSync } from "atom.io/web"
@@ -131,8 +131,8 @@ export function attachDevtoolsStates(
 		do: ({ get, set }, path, current) => {
 			const currentView = get(devtoolsViewSelectionAtom)
 			let states:
-				| WritableTokenIndex<AtomToken<unknown, any, any>>
-				| WritableTokenIndex<SelectorToken<unknown, any, any>>
+				| ReadonlyTokenIndex<AtomToken<unknown, any, any>>
+				| ReadonlyTokenIndex<SelectorToken<unknown, any, any>>
 			switch (currentView) {
 				case `atoms`:
 					states = get(introspectionStates.atomIndex)

package/src/realtime-client/continuity/register-and-attempt-confirmed-update.ts

@@ -18,10 +18,10 @@ export const useRegisterAndAttemptConfirmedUpdate =
 		store: RootStore,
 		continuityKey: string,
 		socket: Socket,
-		optimisticUpdates: AtomIO.TransactionOutcomeEvent<
+		optimisticUpdates: readonly AtomIO.TransactionOutcomeEvent<
 			AtomIO.TransactionToken<Fn>
 		>[],
-		confirmedUpdates: AtomIO.TransactionOutcomeEvent<
+		confirmedUpdates: readonly AtomIO.TransactionOutcomeEvent<
 			AtomIO.TransactionToken<Fn>
 		>[],
 	) =>