atom.io 0.31.0 → 0.32.0

package/src/join.ts

@@ -0,0 +1,218 @@
+import type { MutableAtomFamilyToken, ReadonlySelectorToken } from "atom.io"
+import type {
+	Junction,
+	JunctionEntriesBase,
+	JunctionSchemaBase,
+	Refinement,
+	Store,
+} from "atom.io/internal"
+import {
+	editRelationsInStore,
+	findRelationsInStore,
+	getInternalRelationsFromStore,
+	IMPLICIT,
+	Join,
+} from "atom.io/internal"
+import type { Json } from "atom.io/json"
+import type { SetRTX, SetRTXJson } from "atom.io/transceivers/set-rtx"
+
+export interface JoinOptions<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object | null,
+> extends JunctionSchemaBase<ASide, BSide>,
+		Partial<JunctionEntriesBase<AType, BType, Content>> {
+	readonly key: string
+	readonly cardinality: Cardinality
+	readonly isAType: Refinement<string, AType>
+	readonly isBType: Refinement<string, BType>
+}
+
+export type JoinToken<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object | null = null,
+> = {
+	key: string
+	type: `join`
+	cardinality: Cardinality
+	a: ASide
+	b: BSide
+	__aType?: AType
+	__bType?: BType
+	__content?: Content
+}
+
+export function join<
+	const ASide extends string,
+	const AType extends string,
+	const BSide extends string,
+	const BType extends string,
+	const Cardinality extends `1:1` | `1:n` | `n:n`,
+>(
+	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>,
+	defaultContent?: undefined,
+	store?: Store,
+): JoinToken<ASide, AType, BSide, BType, Cardinality, null>
+export function join<
+	const ASide extends string,
+	const AType extends string,
+	const BSide extends string,
+	const BType extends string,
+	const Cardinality extends `1:1` | `1:n` | `n:n`,
+	const Content extends Json.Object,
+>(
+	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
+	defaultContent: Content,
+	store?: Store,
+): JoinToken<ASide, AType, BSide, BType, Cardinality, Content>
+export function join<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object,
+>(
+	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
+	defaultContent: Content | undefined,
+	store: Store = IMPLICIT.STORE,
+): JoinToken<ASide, AType, BSide, BType, Cardinality, Content> {
+	store.joins.set(options.key, new Join(options, defaultContent, store))
+	const token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content> = {
+		key: options.key,
+		type: `join`,
+		a: options.between[0],
+		b: options.between[1],
+		cardinality: options.cardinality,
+	}
+	return token
+}
+
+export type JoinStates<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object | null,
+> = Cardinality extends `1:1`
+	? (Content extends Json.Object
+			? {
+					readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlySelectorToken<
+						[AType, Content] | null,
+						BType
+					>
+				} & {
+					readonly [B in BSide as `${B}EntryOf${Capitalize<ASide>}`]: ReadonlySelectorToken<
+						[BType, Content] | null,
+						AType
+					>
+				}
+			: {}) & {
+			readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlySelectorToken<
+				AType | null,
+				BType
+			>
+		} & {
+			readonly [B in BSide as `${B}KeyOf${Capitalize<ASide>}`]: ReadonlySelectorToken<
+				BType | null,
+				AType
+			>
+		}
+	: Cardinality extends `1:n`
+		? (Content extends Json.Object
+				? {
+						readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlySelectorToken<
+							[AType, Content] | null,
+							BType
+						>
+					} & {
+						readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlySelectorToken<
+							[BType, Content][],
+							AType
+						>
+					}
+				: {}) & {
+				readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlySelectorToken<
+					AType | null,
+					BType
+				>
+			} & {
+				readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlySelectorToken<
+					BType[],
+					AType
+				>
+			}
+		: Cardinality extends `n:n`
+			? (Content extends Json.Object
+					? {
+							readonly [A in ASide as `${A}EntriesOf${Capitalize<BSide>}`]: ReadonlySelectorToken<
+								[AType, Content][],
+								BType
+							>
+						} & {
+							readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlySelectorToken<
+								[BType, Content][],
+								AType
+							>
+						}
+					: {}) & {
+					readonly [A in ASide as `${A}KeysOf${Capitalize<BSide>}`]: ReadonlySelectorToken<
+						AType[],
+						BType
+					>
+				} & {
+					readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlySelectorToken<
+						BType[],
+						AType
+					>
+				}
+			: never
+
+export function findRelations<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object | null,
+>(
+	token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>,
+	key: AType | BType,
+): JoinStates<ASide, AType, BSide, BType, Cardinality, Content> {
+	return findRelationsInStore(token, key, IMPLICIT.STORE)
+}
+
+export function editRelations<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object | null,
+>(
+	token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>,
+	change: (relations: Junction<ASide, AType, BSide, BType, Content>) => void,
+): void {
+	editRelationsInStore(token, change, IMPLICIT.STORE)
+}
+
+export function getInternalRelations<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object | null,
+>(
+	token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>,
+): MutableAtomFamilyToken<SetRTX<string>, SetRTXJson<string>, string> {
+	return getInternalRelationsFromStore(token, IMPLICIT.STORE)
+}

package/src/realm.ts

@@ -0,0 +1,169 @@
+import type { Each, Store } from "atom.io/internal"
+import {
+	allocateIntoStore,
+	claimWithinStore,
+	deallocateFromStore,
+	fuseWithinStore,
+	IMPLICIT,
+	makeRootMoleculeInStore,
+} from "atom.io/internal"
+import type { Canonical } from "atom.io/json"
+
+export const $claim = Symbol(`claim`)
+export type Claim<K extends Canonical> = K & { [$claim]?: true }
+
+export class Realm<H extends Hierarchy> {
+	public store: Store
+	public constructor(store: Store = IMPLICIT.STORE) {
+		this.store = store
+		makeRootMoleculeInStore(`root`, store)
+	}
+	public allocate<V extends Vassal<H>, A extends Above<V, H>>(
+		provenance: A,
+		key: V,
+		attachmentStyle?: `all` | `any`,
+	): Claim<V> {
+		return allocateIntoStore<H, V, A>(
+			this.store,
+			provenance,
+			key,
+			attachmentStyle,
+		)
+	}
+	public fuse<
+		C extends CompoundFrom<H>,
+		T extends C extends CompoundTypedKey<infer t, any, any> ? t : never,
+		A extends C extends CompoundTypedKey<any, infer v, any> ? v : never,
+		B extends C extends CompoundTypedKey<any, any, infer m> ? m : never,
+	>(
+		type: T,
+		reagentA: SingularTypedKey<A>,
+		reagentB: SingularTypedKey<B>,
+	): Claim<CompoundTypedKey<T, A, B>> {
+		return fuseWithinStore<H, C, T, A, B>(this.store, type, reagentA, reagentB)
+	}
+
+	public deallocate<V extends Vassal<H>>(claim: Claim<V>): void {
+		deallocateFromStore<H, V>(this.store, claim)
+	}
+	public claim<
+		V extends Exclude<Vassal<H>, CompoundTypedKey>,
+		A extends Above<V, H>,
+	>(newProvenance: A, claim: Claim<V>, exclusive?: `exclusive`): Claim<V> {
+		return claimWithinStore<H, V, A>(this.store, newProvenance, claim, exclusive)
+	}
+}
+
+export class Anarchy {
+	public store: Store
+	public realm: Realm<any>
+
+	public constructor(store: Store = IMPLICIT.STORE) {
+		this.store = store
+		this.realm = new Realm(store)
+	}
+
+	public allocate(
+		provenance: Canonical,
+		key: Canonical,
+		attachmentStyle?: `all` | `any`,
+	): void {
+		allocateIntoStore<any, any, any>(
+			this.store,
+			provenance,
+			key,
+			attachmentStyle,
+		)
+	}
+
+	public deallocate(key: Canonical): void {
+		deallocateFromStore<any, any>(this.store, key)
+	}
+
+	public claim(
+		newProvenance: Canonical,
+		key: Canonical,
+		exclusive?: `exclusive`,
+	): void {
+		claimWithinStore<any, any, any>(this.store, newProvenance, key, exclusive)
+	}
+}
+
+export const T$ = `T$`
+export type T$ = typeof T$
+export type TypeTag<T extends string> = `${T$}--${T}`
+export type SingularTypedKey<T extends string = string> = `${T}::${string}`
+export type CompoundTypedKey<
+	A extends string = string,
+	B extends string = string,
+	C extends string = string,
+> = `${TypeTag<A>}==${SingularTypedKey<B>}++${SingularTypedKey<C>}`
+export type TypedKey<
+	A extends string = string,
+	B extends string = string,
+	C extends string = string,
+> = CompoundTypedKey<A, B, C> | SingularTypedKey<A>
+type Scope = SingularTypedKey[]
+type MutualFealty = {
+	above: Scope
+	below: CompoundTypedKey
+}
+type ExclusiveFealty = {
+	above: TypedKey | `root`
+	below: Scope
+}
+type Fealty = ExclusiveFealty | MutualFealty
+
+export type Hierarchy<F extends Fealty[] = Fealty[]> = Each<F>
+
+export type Vassal<H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? H[K][`below`]
+		: H[K] extends { below: Array<infer V> }
+			? V extends TypedKey
+				? V
+				: never
+			: never
+}[keyof H]
+
+export type Above<TK extends TypedKey, H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? TK extends H[K][`below`]
+			? H[K][`above`]
+			: never
+		: H[K] extends { below: Array<infer V> }
+			? TK extends V
+				? H[K] extends ExclusiveFealty
+					? H[K][`above`]
+					: never
+				: never
+			: never
+}[keyof H]
+
+export type Below<TK extends TypedKey | TypedKey[], H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? TK extends H[K][`above`]
+			? H[K][`below`]
+			: TK extends H[K][`above`][number]
+				? H[K][`below`]
+				: never
+		: H[K] extends { above: infer V }
+			? TK extends V
+				? H[K] extends ExclusiveFealty
+					? H[K][`below`][number]
+					: never
+				: never
+			: never
+}[keyof H]
+
+export type Mutuals<TK extends TypedKey | TypedKey[], H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? TK extends H[K][`above`][number]
+			? [mutual: Exclude<H[K][`above`][number], TK>, below: H[K][`below`]]
+			: never
+		: never
+}[keyof H]
+
+export type CompoundFrom<H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty ? H[K][`below`] : never
+}[keyof H]

package/src/selector.ts

@@ -18,9 +18,29 @@ export type ReadonlySelectorOptions<T> = {
 	get: Read<() => T>
 }
 
+/**
+ * @public
+ * Declare a selector. The value of a selector should depend
+ * on the value of atoms or other selectors in the store.
+ *
+ * A writable selector can be "set" to a new value.
+ * It is advised to set its dependencies to values
+ * that would produce the new value of the selector.
+ * @param options - {@link WritableSelectorOptions}.
+ * @returns
+ * The token for your selector.
+ * @overload Writable
+ */
 export function selector<T>(
 	options: WritableSelectorOptions<T>,
 ): WritableSelectorToken<T>
+
+/**
+ * @public
+ * Declare a selector. The value of a selector should depend
+ * on the value of atoms or other selectors in the store.
+ * @param options - {@link ReadonlySelectorOptions}.
+ */
 export function selector<T>(
 	options: ReadonlySelectorOptions<T>,
 ): ReadonlySelectorToken<T>

package/src/set-state.ts

@@ -3,41 +3,49 @@ import type { Canonical } from "atom.io/json"
 
 import type { WritableFamilyToken, WritableToken } from "."
 
+/**
+ * @public
+ * A function that sets the value of a state.
+ * @param oldValue - The current value of the state.
+ * @returns
+ * The new value of the state.
+ */
+export type Setter<T, New extends T> = (oldValue: T) => New
+
 /**
  * @public
  * Set the value of a state into the implicit store.
- * @param token - The unique identifier of the state to set.
+ * @param token - An atom or writable selector token.
  * @param value - The new value of the state.
  * @overload Default
  * @default
  */
 export function setState<T, New extends T>(
 	token: WritableToken<T>,
-	value: New | ((oldValue: T) => New),
+	value: New | Setter<T, New>,
 ): void
 
 /**
  * @public
  * Set the value of a state into the implicit store.
- * @param token - The unique identifier of a state family.
- * @param key - The key of the state to set.
+ * @param token - An atom family or writable selector family token.
+ * @param key - The unique key of the state to set.
  * @param value - The new value of the state.
  * @overload Streamlined
  */
 export function setState<T, K extends Canonical, New extends T, Key extends K>(
 	token: WritableFamilyToken<T, K>,
 	key: Key,
-	value: New | ((oldValue: T) => New),
+	value: New | Setter<T, New>,
 ): void
-
 export function setState<T, New extends T>(
 	...params:
 		| [
 				token: WritableFamilyToken<T, Canonical>,
 				key: Canonical,
-				value: New | ((oldValue: T) => New),
+				value: New | Setter<T, New>,
 		  ]
-		| [token: WritableToken<T>, value: New | ((oldValue: T) => New)]
+		| [token: WritableToken<T>, value: New | Setter<T, New>]
 ): void {
 	if (params.length === 2) {
 		Internal.setIntoStore(Internal.IMPLICIT.STORE, ...params)

package/src/silo.ts

@@ -1,4 +1,4 @@
-import type { findState } from "atom.io/ephemeral"
+import type { findState } from "atom.io"
 import {
 	actUponStore,
 	arbitrary,
@@ -11,13 +11,16 @@ import {
 	disposeFromStore,
 	findInStore,
 	getFromStore,
+	IMPLICIT,
 	setIntoStore,
 	Store,
 	subscribeInStore,
 	timeTravel,
 } from "atom.io/internal"
 
+import { installIntoStore } from "../internal/src/install-into-store"
 import type {
+	AtomIOToken,
 	disposeState,
 	getState,
 	redo,
@@ -45,11 +48,11 @@ export class Silo {
 	public subscribe: typeof subscribe
 	public undo: typeof undo
 	public redo: typeof redo
-
 	public runTransaction: typeof runTransaction
+	public install: (tokens: AtomIOToken[], store?: Store) => void
+
 	public constructor(config: Store[`config`], fromStore: Store | null = null) {
-		const s = new Store(config, fromStore)
-		this.store = s
+		const s = (this.store = new Store(config, fromStore))
 		this.atom = ((options: Parameters<typeof atom>[0]) =>
 			createStandaloneAtom(s, options)) as typeof atom
 		this.atomFamily = ((options: Parameters<typeof atomFamily>[0]) =>
@@ -58,8 +61,8 @@ export class Silo {
 			createStandaloneSelector(s, options)) as typeof selector
 		this.selectorFamily = ((options: Parameters<typeof selectorFamily>[0]) =>
 			createSelectorFamily(s, options)) as typeof selectorFamily
-		this.transaction = (options) => createTransaction(options, s)
-		this.timeline = (options) => createTimeline(options, s)
+		this.transaction = (options) => createTransaction(s, options)
+		this.timeline = (options) => createTimeline(s, options)
 		this.findState = ((...params: Parameters<typeof findState>) =>
 			findInStore(s, ...params)) as typeof findState
 		this.getState = ((...params: Parameters<typeof getState>) =>
@@ -78,6 +81,9 @@ export class Silo {
 		this.redo = (token) => {
 			timeTravel(s, `redo`, token)
 		}
-		this.runTransaction = (token, id = arbitrary()) => actUponStore(token, id, s)
+		this.runTransaction = (token, id = arbitrary()) => actUponStore(s, token, id)
+		this.install = (tokens, source = IMPLICIT.STORE) => {
+			installIntoStore(tokens, s, source)
+		}
 	}
 }

package/src/timeline.ts

@@ -49,7 +49,7 @@ export type TimelineUpdate<ManagedAtom extends TimelineManageable> =
 export const timeline = <ManagedAtom extends TimelineManageable>(
 	options: TimelineOptions<ManagedAtom>,
 ): TimelineToken<ManagedAtom> => {
-	return createTimeline(options, IMPLICIT.STORE)
+	return createTimeline(IMPLICIT.STORE, options)
 }
 
 export const redo = (tl: TimelineToken<any>): void => {

package/src/transaction.ts

@@ -1,6 +1,4 @@
-import type { getState, setState } from "atom.io"
-import type { findState } from "atom.io/ephemeral"
-import type { seekState } from "atom.io/immortal"
+import type { findState, getState, setState } from "atom.io"
 import type { EnvironmentData, Func, Transceiver } from "atom.io/internal"
 import {
 	actUponStore,
@@ -83,12 +81,11 @@ export type TransactionUpdate<F extends Func> = {
 	output: ReturnType<F>
 }
 
-export type GetterToolkit = Pick<SetterToolkit, `find` | `get` | `json` | `seek`>
+export type GetterToolkit = Pick<SetterToolkit, `find` | `get` | `json`>
 export type SetterToolkit = Readonly<{
 	get: typeof getState
 	set: typeof setState
 	find: typeof findState
-	seek: typeof seekState
 	json: <T extends Transceiver<any>, J extends Json.Serializable>(
 		state: MutableAtomToken<T, J>,
 	) => WritableSelectorToken<J>
@@ -97,7 +94,6 @@ export type ActorToolkit = Readonly<{
 	get: typeof getState
 	set: typeof setState
 	find: typeof findState
-	seek: typeof seekState
 	json: <T extends Transceiver<any>, J extends Json.Serializable>(
 		state: MutableAtomToken<T, J>,
 	) => WritableSelectorToken<J>
@@ -132,12 +128,12 @@ export type TransactionIO<Token extends TransactionToken<any>> =
 export function transaction<F extends Func>(
 	options: TransactionOptions<F>,
 ): TransactionToken<F> {
-	return createTransaction(options, IMPLICIT.STORE)
+	return createTransaction(IMPLICIT.STORE, options)
 }
 
 export function runTransaction<F extends Func>(
 	token: TransactionToken<F>,
 	id = arbitrary(),
 ): (...parameters: Parameters<F>) => ReturnType<F> {
-	return actUponStore(token, id, IMPLICIT.STORE)
+	return actUponStore(IMPLICIT.STORE, token, id)
 }

package/transceivers/set-rtx/dist/index.d.ts

@@ -1,5 +1,40 @@
-import { Transceiver, Lineage, TransceiverMode, Subject } from 'atom.io/internal';
-import { primitive, Json } from 'atom.io/json';
+type primitive = boolean | number | string | null;
+declare namespace Json {
+    namespace Tree {
+        type Array<Element = unknown> = ReadonlyArray<Element>;
+        type Object<K extends string = string, V = unknown> = Record<K, V>;
+        type Fork = Array | Object;
+        type Leaf = primitive;
+        type Node = Fork | Leaf;
+    }
+    type Serializable = primitive | Readonly<{
+        [key: string]: Serializable;
+    }> | ReadonlyArray<Serializable>;
+    type Object<Key extends string = string, Value extends Serializable = Serializable> = Record<Key, Value>;
+    type Array<Element extends Serializable = Serializable> = ReadonlyArray<Element>;
+}
+
+declare class Subject<T> {
+    Subscriber: (value: T) => void;
+    subscribers: Map<string, this[`Subscriber`]>;
+    subscribe(key: string, subscriber: this[`Subscriber`]): () => void;
+    private unsubscribe;
+    next(value: T): void;
+}
+
+interface Lineage {
+    parent: typeof this | null;
+    child: typeof this | null;
+}
+
+interface Transceiver<S extends Json.Serializable> {
+    do: (update: S) => number | `OUT_OF_RANGE` | null;
+    undo: (update: S) => void;
+    subscribe: (key: string, fn: (update: S) => void) => () => void;
+    cacheUpdateNumber: number;
+    getUpdateNumber: (update: S) => number;
+}
+type TransceiverMode = `playback` | `record` | `transaction`;
 
 type SetUpdate = `add:${string}` | `clear:${string}` | `del:${string}` | `tx:${string}`;
 type NumberedSetUpdate = `${number}=${SetUpdate}`;