atom.io 0.44.14 → 0.45.0

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/main/logger.ts

@@ -82,6 +82,7 @@ export type EntityDenomination =
 	| `timeline`
 	| `transaction`
 	| `unknown`
+	| `user`
 	| `writable_held_selector_family`
 	| `writable_held_selector`
 	| `writable_pure_selector_family`
@@ -103,6 +104,7 @@ export const PRETTY_ENTITY_NAMES: Record<EntityDenomination, string> = {
 	timeline: `timeline`,
 	transaction: `transaction`,
 	unknown: `unknown`,
+	user: `👤`,
 	writable_held_selector_family: `selector family [wh]`,
 	writable_held_selector: `selector [wh]`,
 	writable_pure_selector_family: `selector family [w]`,
@@ -126,11 +128,11 @@ export type LogFilter = (
 export type Logger = Record<LogLevel, LogFn>
 
 export const simpleLog =
-	(logLevel: keyof Logger): LogFn =>
+	(logLevel: keyof Logger, prefix?: string): LogFn =>
 	(icon, denomination, tokenKey, message, ...rest) => {
 		/* eslint-disable-next-line no-console */
 		console[logLevel](
-			`${icon} ${PRETTY_ENTITY_NAMES[denomination]} \`${tokenKey}\` ${message}`,
+			`${prefix ? `${prefix} ` : ``}${icon} ${PRETTY_ENTITY_NAMES[denomination]} \`${tokenKey}\` ${message}`,
 			...rest,
 		)
 	}

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>
 		>[],
 	) =>

package/src/realtime-server/realtime-family-provider.ts

@@ -14,6 +14,7 @@ import type { ServerConfig } from "."
 export type FamilyProvider = ReturnType<typeof realtimeAtomFamilyProvider>
 export function realtimeAtomFamilyProvider({
 	socket,
+	userKey,
 	store = IMPLICIT.STORE,
 }: ServerConfig) {
 	return function familyProvider<
@@ -66,6 +67,12 @@ export function realtimeAtomFamilyProvider({
 			familyMemberSubscriptions.set(
 				`${token.key}:unsub`,
 				employSocket(socket, `unsub:${token.key}`, () => {
+					store.logger.info(
+						`🙈`,
+						`user`,
+						userKey,
+						`unsubscribed from state "${token.key}"`,
+					)
 					fillUnsubRequest(token.key)
 				}),
 			)
@@ -81,13 +88,35 @@ export function realtimeAtomFamilyProvider({
 		}
 
 		const start = () => {
+			store.logger.info(
+				`👀`,
+				`user`,
+				userKey,
+				`can subscribe to family "${family.key}"`,
+			)
 			coreSubscriptions.add(
 				employSocket(socket, `sub:${family.key}`, (subKey: K) => {
 					const exposedSubKeys = getFromStore(store, index)
 					const shouldExpose = isAvailable(exposedSubKeys, subKey)
 					if (shouldExpose) {
+						store.logger.info(
+							`👀`,
+							`user`,
+							userKey,
+							`is approved for a subscription to`,
+							subKey,
+							`in family "${family.key}"`,
+						)
 						exposeFamilyMembers(subKey)
 					} else {
+						store.logger.info(
+							`❌`,
+							`user`,
+							userKey,
+							`is denied for a subscription to`,
+							subKey,
+							`in family "${family.key}"`,
+						)
 						familyMemberSubscriptionsWanted.add(stringifyJson(subKey))
 						socket.emit(`unavailable:${family.key}`, subKey)
 					}
@@ -99,8 +128,23 @@ export function realtimeAtomFamilyProvider({
 					index,
 					`expose-family:${family.key}:${socket.id}`,
 					({ newValue: newExposedSubKeys }) => {
+						store.logger.info(
+							`👀`,
+							`user`,
+							userKey,
+							`has the following keys available for family "${family.key}"`,
+							newExposedSubKeys,
+						)
 						for (const subKey of newExposedSubKeys) {
 							if (familyMemberSubscriptionsWanted.has(stringifyJson(subKey))) {
+								store.logger.info(
+									`👀`,
+									`user`,
+									userKey,
+									`is retroactively approved for a subscription to`,
+									subKey,
+									`in family "${family.key}"`,
+								)
 								exposeFamilyMembers(subKey)
 							}
 						}

package/src/realtime-server/realtime-mutable-family-provider.ts

@@ -31,6 +31,7 @@ export type MutableFamilyProvider = ReturnType<
 >
 export function realtimeMutableFamilyProvider({
 	socket,
+	userKey,
 	store = IMPLICIT.STORE,
 }: ServerConfig) {
 	return function mutableFamilyProvider<
@@ -91,13 +92,35 @@ export function realtimeMutableFamilyProvider({
 		}
 
 		const start = () => {
+			store.logger.info(
+				`👀`,
+				`user`,
+				userKey,
+				`can subscribe to family "${family.key}"`,
+			)
 			coreSubscriptions.add(
 				employSocket(socket, `sub:${family.key}`, (subKey: K) => {
 					const exposedSubKeys = getFromStore(store, index)
 					const shouldExpose = isAvailable(exposedSubKeys, subKey)
 					if (shouldExpose) {
+						store.logger.info(
+							`👀`,
+							`user`,
+							userKey,
+							`is approved for a subscription to`,
+							subKey,
+							`in family "${family.key}"`,
+						)
 						exposeFamilyMembers(subKey)
 					} else {
+						store.logger.info(
+							`❌`,
+							`user`,
+							userKey,
+							`is denied for a subscription to`,
+							subKey,
+							`in family "${family.key}"`,
+						)
 						familyMemberSubscriptionsWanted.add(stringifyJson(subKey))
 						socket.emit(`unavailable:${family.key}`, subKey)
 					}
@@ -109,8 +132,23 @@ export function realtimeMutableFamilyProvider({
 					index,
 					`expose-family:${family.key}:${socket.id}`,
 					({ newValue: newExposedSubKeys }) => {
+						store.logger.info(
+							`👀`,
+							`user`,
+							userKey,
+							`has the following keys available for family "${family.key}"`,
+							newExposedSubKeys,
+						)
 						for (const subKey of newExposedSubKeys) {
 							if (familyMemberSubscriptionsWanted.has(stringifyJson(subKey))) {
+								store.logger.info(
+									`👀`,
+									`user`,
+									userKey,
+									`is retroactively approved for a subscription to`,
+									subKey,
+									`in family "${family.key}"`,
+								)
 								exposeFamilyMembers(subKey)
 							}
 						}

package/src/realtime-server/realtime-mutable-provider.ts

@@ -15,6 +15,7 @@ import type { ServerConfig } from "."
 export type MutableProvider = ReturnType<typeof realtimeMutableProvider>
 export function realtimeMutableProvider({
 	socket,
+	userKey,
 	store = IMPLICIT.STORE,
 }: ServerConfig) {
 	return function mutableProvider<
@@ -30,8 +31,20 @@ export function realtimeMutableProvider({
 		const trackerToken = getUpdateToken(token)
 
 		const start = () => {
+			store.logger.info(
+				`👀`,
+				`user`,
+				userKey,
+				`can subscribe to state "${token.key}"`,
+			)
 			subscriptions.add(
 				employSocket(socket, `sub:${token.key}`, () => {
+					store.logger.info(
+						`👀`,
+						`user`,
+						userKey,
+						`subscribes to state "${token.key}"`,
+					)
 					clearSubscriptions()
 					socket.emit(`init:${token.key}`, getFromStore(store, jsonToken))
 					subscriptions.add(
@@ -46,6 +59,12 @@ export function realtimeMutableProvider({
 					)
 					subscriptions.add(
 						employSocket(socket, `unsub:${token.key}`, () => {
+							store.logger.info(
+								`🙈`,
+								`user`,
+								userKey,
+								`unsubscribes from state "${token.key}"`,
+							)
 							clearSubscriptions()
 							start()
 						}),

package/src/realtime-server/realtime-server-stores/provide-rooms.ts

@@ -252,10 +252,11 @@ export function provideRooms<RoomNames extends string>({
 		createRoomSocketGuard(roomNames),
 	)
 
-	const exposeMutable = realtimeMutableProvider({ socket, store })
+	const exposeMutable = realtimeMutableProvider({ socket, store, userKey })
 	const exposeMutableFamily = realtimeMutableFamilyProvider({
 		socket,
 		store,
+		userKey,
 	})
 
 	exposeMutable(roomKeysAtom)

package/src/realtime-server/realtime-state-provider.ts

@@ -8,8 +8,10 @@ import type { ServerConfig } from "."
 export type StateProvider = ReturnType<typeof realtimeStateProvider>
 export function realtimeStateProvider({
 	socket,
+	userKey,
 	store = IMPLICIT.STORE,
 }: ServerConfig) {
+	store.logger.info(`🔌`, `user`, userKey, `initialized state provider`)
 	return function stateProvider<J extends Json.Serializable>(
 		token: AtomIO.WritableToken<J>,
 	): () => void {
@@ -20,8 +22,20 @@ export function realtimeStateProvider({
 		}
 
 		const start = () => {
+			store.logger.info(
+				`👀`,
+				`user`,
+				userKey,
+				`can subscribe to state "${token.key}"`,
+			)
 			subscriptions.add(
 				employSocket(socket, `sub:${token.key}`, () => {
+					store.logger.info(
+						`👀`,
+						`user`,
+						userKey,
+						`subscribes to state "${token.key}"`,
+					)
 					clearSubscriptions()
 					socket.emit(`serve:${token.key}`, getFromStore(store, token))
 					subscriptions.add(
@@ -36,6 +50,12 @@ export function realtimeStateProvider({
 					)
 					subscriptions.add(
 						employSocket(socket, `unsub:${token.key}`, () => {
+							store.logger.info(
+								`🙈`,
+								`user`,
+								userKey,
+								`unsubscribes from state "${token.key}"`,
+							)
 							clearSubscriptions()
 							start()
 						}),

package/src/realtime-server/server-config.ts

@@ -1,7 +1,8 @@
 import type { RootStore } from "atom.io/internal"
-import type { Socket } from "atom.io/realtime"
+import type { Socket, UserKey } from "atom.io/realtime"
 
 export type ServerConfig = {
 	socket: Socket
+	userKey: UserKey
 	store?: RootStore
 }

package/src/realtime-testing/setup-realtime-test.tsx

@@ -54,15 +54,9 @@ function prefixLogger(store: Store, prefix: string) {
 			return params
 		},
 		{
-			info: (...params) => {
-				console.info(prefix, ...params)
-			},
-			warn: (...params) => {
-				console.warn(prefix, ...params)
-			},
-			error: (...params) => {
-				console.error(prefix, ...params)
-			},
+			info: AtomIO.simpleLog(`info`, prefix),
+			warn: AtomIO.simpleLog(`warn`, prefix),
+			error: AtomIO.simpleLog(`error`, prefix),
 		},
 	)
 }