atom.io 0.0.0

package/README.md

@@ -0,0 +1,30 @@
+# MVP
+- [x] atoms and selectors
+- [x] implicit store
+- [x] readonly selectors
+- [x] settable selectors
+- [x] safe recursive update propagation
+- [x] safely expose atoms and selectors
+- [x] give atoms and selectors separate types with a common base
+- [x] utility function to pass logger to your store
+- [x] selector memoization
+- [x] atom and selector families
+- [x] atom effects
+- [x] transactions
+
+# Features
+- [ ] atom default as function
+- [ ] atom default as promise
+- [ ] resettable atoms
+- [ ] resettable selectors
+- [ ] optional default value for atoms
+- [ ] optional state keys
+- [ ] subscribe to transactions
+- [ ] logging levels (debug, info, warn, error)
+
+# Performance Enhancements
+- [ ] refactor selector dependencies to be asymmetrical
+      this would permit us to rebuild the dependency graph on every update,
+      meaning more efficient memoization
+- [ ] only propagate updates downstream to selectors with an active subscription
+- [ ] trampoline for recursive propagation

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+import * as Rx from 'rxjs';
+import { Hamt } from 'hamt_plus';
+import { Refinement } from 'fp-ts/Refinement';
+
+type Primitive = boolean | number | string | null;
+type Serializable = Primitive | Readonly<{
+    [key: string]: Serializable;
+}> | ReadonlyArray<Serializable>;
+type JsonObj<Key extends string = string, Value extends Serializable = Serializable> = Record<Key, Value>;
+type JsonArr<Element extends Serializable = Serializable> = ReadonlyArray<Element>;
+type Json = JsonArr | JsonObj | Primitive;
+
+type Identified = {
+    id: string;
+};
+
+declare const RELATION_TYPES: readonly ["1:1", "1:n", "n:n"];
+type RelationType = (typeof RELATION_TYPES)[number];
+type RelationData<CONTENT extends JsonObj | null = null> = {
+    contents: JsonObj<string, CONTENT>;
+    relations: JsonObj<string, string[]>;
+    relationType: RelationType;
+};
+
+type NullSafeUnion<Base, Extension> = Extension extends null ? Base : Base & Extension;
+type NullSafeRest<MaybeArg> = MaybeArg extends null ? [] | [undefined] : [MaybeArg];
+
+declare class Join<CONTENT extends JsonObj | null = null> implements RelationData<CONTENT> {
+    readonly relationType: `1:1` | `1:n` | `n:n`;
+    readonly relations: Record<string, string[]>;
+    readonly contents: Record<string, CONTENT>;
+    constructor(json?: Partial<RelationData<CONTENT>>);
+    toJSON(): RelationData<CONTENT>;
+    static fromJSON<CONTENT extends JsonObj | null = null>(json: Json, isContent?: Refinement<unknown, CONTENT>): Join<CONTENT>;
+    getRelatedId(id: string): string | undefined;
+    getRelatedIds(id: string): string[];
+    getContent(idA: string, idB: string): CONTENT | undefined;
+    getRelationEntries(id: string): [string, CONTENT][];
+    getRelationRecord(id: string): Record<string, CONTENT>;
+    getRelation(id: string): NullSafeUnion<Identified, CONTENT> | undefined;
+    getRelations(id: string): NullSafeUnion<Identified, CONTENT>[];
+    setRelations(id: string, relations: NullSafeUnion<Identified, CONTENT>[]): Join<CONTENT>;
+    set(idA: string, idB: string, ...rest: NullSafeRest<CONTENT>): Join<CONTENT>;
+    remove(idA: string, idB?: string): Join<CONTENT>;
+}
+
+interface Store {
+    valueMap: Hamt<any, string>;
+    selectorGraph: Join;
+    selectors: Hamt<Selector<any>, string>;
+    readonlySelectors: Hamt<ReadonlySelector<any>, string>;
+    atoms: Hamt<Atom<any>, string>;
+    operation: {
+        open: false;
+    } | {
+        open: true;
+        done: Set<string>;
+        prev: Hamt<any, string>;
+    };
+    transaction: {
+        open: false;
+    } | {
+        open: true;
+        prev: Pick<Store, `atoms` | `readonlySelectors` | `selectorGraph` | `selectors` | `valueMap`>;
+    };
+    config: {
+        name: string;
+        logger: Pick<Console, `error` | `info` | `warn`> | null;
+    };
+}
+declare const createStore: (name: string) => Store;
+declare const IMPLICIT: {
+    STORE_INTERNAL: Store | undefined;
+    readonly STORE: Store;
+};
+declare const configure: (config: Partial<Store[`config`]>, store?: Store) => void;
+declare const clearStore: (store?: Store) => void;
+
+declare const getCachedState: <T>(state: Atom<T> | Selector<T> | ReadonlySelector<T>, store?: Store) => T;
+declare const getSelectorState: <T>(selector: Selector<T> | ReadonlySelector<T>) => T;
+declare function withdraw<T>(token: AtomToken<T>, store: Store): Atom<T>;
+declare function withdraw<T>(token: SelectorToken<T>, store: Store): Selector<T>;
+declare function withdraw<T>(token: StateToken<T>, store: Store): Atom<T> | Selector<T>;
+declare function withdraw<T>(token: ReadonlyValueToken<T>, store: Store): ReadonlySelector<T>;
+declare function withdraw<T>(token: ReadonlyValueToken<T> | StateToken<T>, store: Store): Atom<T> | ReadonlySelector<T> | Selector<T>;
+declare function deposit<T>(state: Atom<T>): AtomToken<T>;
+declare function deposit<T>(state: Selector<T>): SelectorToken<T>;
+declare function deposit<T>(state: Atom<T> | Selector<T>): StateToken<T>;
+declare function deposit<T>(state: ReadonlySelector<T>): ReadonlyValueToken<T>;
+declare function deposit<T>(state: Atom<T> | ReadonlySelector<T> | Selector<T>): ReadonlyValueToken<T> | StateToken<T>;
+declare const getState__INTERNAL: <T>(state: Atom<T> | Selector<T> | ReadonlySelector<T>, store?: Store) => T;
+
+declare const propagateChanges: <T>(state: Atom<T> | Selector<T>, store?: Store) => void;
+declare const setAtomState: <T>(atom: Atom<T>, next: T | ((oldValue: T) => T), store?: Store) => void;
+declare const setSelectorState: <T>(selector: Selector<T>, next: T | ((oldValue: T) => T), store?: Store) => void;
+declare const setState__INTERNAL: <T>(token: StateToken<T>, value: T | ((oldValue: T) => T), store?: Store) => void;
+
+declare const finishAction: (store: Store) => void;
+declare const startAction: (store: Store) => void;
+declare const isDone: (key: string, store?: Store) => boolean;
+declare const markDone: (key: string, store?: Store) => void;
+declare const recall: <T>(state: Atom<T> | Selector<T> | ReadonlySelector<T>, store?: Store) => T;
+
+declare const finishTransaction: (store: Store) => void;
+declare const startTransaction: (store: Store) => void;
+declare const abortTransaction: (store: Store) => void;
+
+type Atom<T> = {
+    key: string;
+    subject: Rx.Subject<{
+        newValue: T;
+        oldValue: T;
+    }>;
+    default: T;
+};
+type Selector<T> = {
+    key: string;
+    subject: Rx.Subject<{
+        newValue: T;
+        oldValue: T;
+    }>;
+    get: () => T;
+    set: (newValue: T | ((oldValue: T) => T)) => void;
+};
+type ReadonlySelector<T> = Omit<Selector<T>, `set`>;
+
+type index_Atom<T> = Atom<T>;
+declare const index_IMPLICIT: typeof IMPLICIT;
+type index_ReadonlySelector<T> = ReadonlySelector<T>;
+type index_Selector<T> = Selector<T>;
+type index_Store = Store;
+declare const index_abortTransaction: typeof abortTransaction;
+declare const index_clearStore: typeof clearStore;
+declare const index_configure: typeof configure;
+declare const index_createStore: typeof createStore;
+declare const index_deposit: typeof deposit;
+declare const index_finishAction: typeof finishAction;
+declare const index_finishTransaction: typeof finishTransaction;
+declare const index_getCachedState: typeof getCachedState;
+declare const index_getSelectorState: typeof getSelectorState;
+declare const index_getState__INTERNAL: typeof getState__INTERNAL;
+declare const index_isDone: typeof isDone;
+declare const index_markDone: typeof markDone;
+declare const index_propagateChanges: typeof propagateChanges;
+declare const index_recall: typeof recall;
+declare const index_setAtomState: typeof setAtomState;
+declare const index_setSelectorState: typeof setSelectorState;
+declare const index_setState__INTERNAL: typeof setState__INTERNAL;
+declare const index_startAction: typeof startAction;
+declare const index_startTransaction: typeof startTransaction;
+declare const index_withdraw: typeof withdraw;
+declare namespace index {
+  export {
+    index_Atom as Atom,
+    index_IMPLICIT as IMPLICIT,
+    index_ReadonlySelector as ReadonlySelector,
+    index_Selector as Selector,
+    index_Store as Store,
+    index_abortTransaction as abortTransaction,
+    index_clearStore as clearStore,
+    index_configure as configure,
+    index_createStore as createStore,
+    index_deposit as deposit,
+    index_finishAction as finishAction,
+    index_finishTransaction as finishTransaction,
+    index_getCachedState as getCachedState,
+    index_getSelectorState as getSelectorState,
+    index_getState__INTERNAL as getState__INTERNAL,
+    index_isDone as isDone,
+    index_markDone as markDone,
+    index_propagateChanges as propagateChanges,
+    index_recall as recall,
+    index_setAtomState as setAtomState,
+    index_setSelectorState as setSelectorState,
+    index_setState__INTERNAL as setState__INTERNAL,
+    index_startAction as startAction,
+    index_startTransaction as startTransaction,
+    index_withdraw as withdraw,
+  };
+}
+
+type Effectors<T> = {
+    setSelf: <V extends T>(next: V | ((oldValue: T) => V)) => void;
+    onSet: (callback: (options: {
+        newValue: T;
+        oldValue: T;
+    }) => void) => void;
+};
+type AtomEffect<T> = (tools: Effectors<T>) => void;
+type AtomOptions<T> = {
+    key: string;
+    default: T;
+    effects?: AtomEffect<T>[];
+};
+declare const atom: <T>(options: AtomOptions<T>, store?: Store) => AtomToken<T>;
+type AtomFamilyOptions<T, K extends Serializable> = {
+    key: string;
+    default: T | ((key: K) => T);
+    effects?: (key: K) => AtomEffect<T>[];
+};
+declare const atomFamily: <T, K extends Serializable>(options: AtomFamilyOptions<T, K>, store?: Store) => (key: K) => AtomToken<T>;
+
+type ƒn = (...parameters: any[]) => any;
+type Transactors = {
+    get: <S>(state: ReadonlyValueToken<S> | StateToken<S>) => S;
+    set: <S>(state: StateToken<S>, newValue: S | ((oldValue: S) => S)) => void;
+};
+type ReadonlyTransactors = Pick<Transactors, `get`>;
+type Action<ƒ extends ƒn> = (transactors: Transactors, ...parameters: Parameters<ƒ>) => ReturnType<ƒ>;
+type TransactionOptions<ƒ extends ƒn> = {
+    key: string;
+    do: Action<ƒ>;
+};
+declare const transaction: <ƒ extends ƒn>(options: TransactionOptions<ƒ>, store?: Store) => ((...parameters: Parameters<ƒ>) => ReturnType<ƒ>) & {
+    key: string;
+};
+
+type SelectorOptions<T> = {
+    key: string;
+    get: (readonlyTransactors: ReadonlyTransactors) => T;
+    set: (transactors: Transactors, newValue: T) => void;
+};
+type ReadonlySelectorOptions<T> = Omit<SelectorOptions<T>, `set`>;
+declare function selector<T>(options: SelectorOptions<T>, store?: Store): SelectorToken<T>;
+declare function selector<T>(options: ReadonlySelectorOptions<T>, store?: Store): ReadonlyValueToken<T>;
+type SelectorFamilyOptions<T, K extends Serializable> = {
+    key: string;
+    get: (key: K) => (readonlyTransactors: ReadonlyTransactors) => T;
+    set: (key: K) => (transactors: Transactors, newValue: T) => void;
+};
+type ReadonlySelectorFamilyOptions<T, K extends Serializable> = Omit<SelectorFamilyOptions<T, K>, `set`>;
+declare function selectorFamily<T, K extends Serializable>(options: SelectorFamilyOptions<T, K>, store?: Store): (key: K) => SelectorToken<T>;
+declare function selectorFamily<T, K extends Serializable>(options: ReadonlySelectorFamilyOptions<T, K>, store?: Store): (key: K) => ReadonlyValueToken<T>;
+declare const registerSelector: (selectorKey: string, store?: Store) => Transactors;
+
+interface AtomToken<_> {
+    key: string;
+    type: `atom`;
+}
+interface SelectorToken<_> {
+    key: string;
+    type: `selector`;
+}
+type StateToken<T> = AtomToken<T> | SelectorToken<T>;
+interface ReadonlyValueToken<_> {
+    key: string;
+    type: `readonly_selector`;
+}
+declare const getState: <T>(token: ReadonlyValueToken<T> | StateToken<T>, store?: Store) => T;
+declare const setState: <State, Value extends State>(state: StateToken<State>, value: Value | ((oldValue: State) => Value), store?: Store) => void;
+type Observe<T> = (change: {
+    newValue: T;
+    oldValue: T;
+}) => void;
+declare const subscribe: <T>(token: ReadonlyValueToken<T> | StateToken<T>, observe: Observe<T>, store?: Store) => (() => void);
+
+export { Action, AtomEffect, AtomFamilyOptions, AtomOptions, AtomToken, Effectors, Observe, ReadonlySelectorFamilyOptions, ReadonlySelectorOptions, ReadonlyTransactors, ReadonlyValueToken, SelectorFamilyOptions, SelectorOptions, SelectorToken, StateToken, TransactionOptions, Transactors, index as __INTERNAL__, atom, atomFamily, configure, getState, registerSelector, selector, selectorFamily, setState, subscribe, transaction, ƒn };