@webkrafters/react-observable-context 6.0.5 → 7.0.0-rc.0

package/README.md

@@ -25,36 +25,151 @@
 <table BORDER-COLOR="0a0" BORDER-WIDTH="2">
     <td VALIGN="middle" ALIGN="center" FONT-WEIGHT="BOLD" COLOR="#333" HEIGHT="250px" width="1250px">
 		COMPATIBLE WITH REACT VERSIONS 16.8 to 18.x.x.<br />
-		A VERSION 7.0.0 FOR REACT 19+ IS CURRENTLY UNDER DEVELOPMENT.
+		A NEW EAGLEEYE BASED PRODUCT WILL BE DEVELOPED SPECIFICALLY FOR REACT 19+<br /><br />
+		PLEASE STAY TUNED.
 	</td>
 </table>
 
 <ul>
-	<li> Auto-immutable update-friendly context. See <a href="https://eagleeye.js.org/concepts/store/setstate"><code>store.setState</code></a>.</li>
-	<li> A context bearing an observable consumer <a href="https://eagleeye.js.org/concepts/store">store</a>.</li>
-	<li> Recognizes <b>negative array indexing</b>. Please see <a href="https://eagleeye.js.org/concepts/property-path">Property Path</a> and <code>store.setState</code> <a href="https://eagleeye.js.org/concepts/store/setstate#indexing">Indexing</a>.</li>
-	<li> Only re-renders subscribing components (<a href="https://eagleeye.js.org/concepts/client">clients</a>) on context state changes.</li>
+	<li> Ready for use anywhere in the app. No Provider components needed.</li>
+	<li> Auto-immutable update-friendly context. See <a href="https://eagleeye.js.org/concepts/store/setstate"><code>store.setState</code> (under revision)</a>.</li>
+	<li> A context bearing an observable consumer <a href="https://eagleeye.js.org/concepts/store">store (under revision)</a>.</li>
+	<li> Recognizes <b>negative array indexing</b>. Please see <a href="https://eagleeye.js.org/concepts/property-path">Property Path (under revision)</a> and <code>store.setState</code> <a href="https://eagleeye.js.org/concepts/store/setstate#indexing">Indexing (under revision)</a>.</li>
+	<li> Only re-renders subscribing components (<a href="https://eagleeye.js.org/concepts/client">clients (under revision)</a>) on context state changes.</li>
 	<li> Subscribing component decides which context state properties' changes to trigger its update.</li>
 </ul>
 
 **Name:** React-Observable-Context
 
-**Moniker:** Eagle Eye
+**Moniker:** Legacy Eagle Eye
 
-**Usage:** Please see <b><a href="https://eagleeye.js.org/getting-started">Getting Started</a></b>.
+**Usage:** Please see <b><a href="https://eagleeye.js.org/getting-started">Getting Started (under revision)</a></b>.
 
-**Demo:** [Play with the app on codesandbox](https://codesandbox.io/s/github/webKrafters/react-observable-context-app)\
+**Demo:** [Play with the app on codesandbox (under revision)](https://codesandbox.io/s/github/webKrafters/react-observable-context-app)\
 If sandbox fails to load app, please refresh dependencies on its lower left.
 
 **Install:**\
-npm i -S @webkrafters/react-observable-context\
-Defunct: npm i -S react-eagleeye
+npm install --save @webkrafters/react-observable-context\
 
-May also see <b><a href="https://eagleeye.js.org/history/features">What's Changed?</a></b>
+## Usage:
+
+```tsx
+import { FC } from 'react';
+import { createEagleEye } from '@webkrafters/react-observable-context';
+
+const context = createEagleEye(
+	T|AutoImmutable<T>?,
+	Prehooks<T>?,
+	IStorage<T>?
+);
+
+// component consuming change stream manually
+const useStream = context.useStream;
+const Component1 : FC = () => {
+	const {
+		data,
+		resetState,
+		setState
+	} = useStream( SelectorMap );
+	...
+};
+
+// components consuming change stream through a reusable adapter
+const connect = context.connect( SelectorMap? );
+const Component2 = connect(({ data, resetState, setState, ...ownProps }) => {...});
+const Component3 = connect(({ data, resetState, setState, ...ownProps }) => {...});
+
+const App : FC = () => (
+	<>
+		<Component1 />
+		<Component2 />
+		<Component3 />
+	</>
+);
+
+```
+
+### Releasing context resources.
+```tsx
+context.dispose();
+```
+Deactivates this context by:
+<ol>
+	<li>unsubscribing all observers to it</li>
+	<li>severing connections to data stores</li>
+	<li>unsetting all resources</li>
+</ol>
+
+### Accessing external store reference.
+```tsx
+const store = context.store;
+// https://eagleeye.js.org/concepts/store/resetstate/
+store.resetState( Array<string>? );
+// https://eagleeye.js.org/concepts/store/setstate/
+store.setState( Changes<T> );
+// https://eagleeye.js.org/concepts/store/getstate/
+const state = store.getState( Array<string> );
+// https://eagleeye.js.org/concepts/store/subscribe/
+const unsubscribeFn = store.subscribe( eventType, listener );
+```
+Any actions taken here is applied to all components streaming affected state slices.\
+Caveat 1: Parameterless <code>context.store.getState</code> returns the whole state.\
+Caveat 2: Parameterless <code>context.store.resetState</code> which is a no-op.
+
+### Joining the context stream.
+A context stream allows a client to set up a dedicated channel through which it receives automatic updates whenever its selected slices of state change. It can also update the context through this channel.
+```tsx
+const useStream = context.stream;
+// joining the stream twice
+// for more on selectorMap - https://eagleeye.js.org/concepts/selector-map/
+const store1 = useStream(SelectorMap?);
+const store2 = useStream(SelectorMap?);
+// access the current data value monitored by this store
+console.log( 'data', store1.data );
+// https://eagleeye.js.org/concepts/store/resetstate/
+store1.resetState( Array<string>? ); // changes are context-wide
+// https://eagleeye.js.org/concepts/store/setstate/
+store1.setState( Changes<T> ); // changes are context-wide
+```
+Any actions taken here is applied to all components streaming affected state slices.\
+Caveat 1: Parameterless <code>store.resetState</code> resets state slices consumed by this store.\
+Caveat 2: Parameterless <code>store.resetState</code> for stores not consuming state is a no-op.
+
+### Accessing underlying cache.
+```tsx
+const cache = context.cache;
+```
+
+### Accessing `close` status.
+```tsx
+const closed = context.closed;
+```
+
+### Accessing current state update `prehooks`.
+```tsx
+const prehooks = context.prehooks;
+```
+
+### Updating state update `prehooks`.
+```tsx
+context.prehooks = Prehooks<T>?;
+```
+
+### Accessing context `storage`.
+```tsx
+const storage = context.storage;
+```
+
+### Updating context `storage`.
+```tsx
+context.storage = IStorage<T>?;
+```
+
+May also see <b><a href="https://eagleeye.js.org/history/features">What's Changed? (currently uunder revision)</a></b>
 
 ## Please see full documentation here:
-**[eagleeye.js.org](https://eagleeye.js.org)**
+**[eagleeye.js.org](https://eagleeye.js.org)** (currently out-of-date pending revision)
 
 # License
 
-MIT
+GPLv3

package/dist/index.d.ts

@@ -1,16 +1,8 @@
-import type { ComponentType, ForwardRefExoticComponent, MemoExoticComponent, NamedExoticComponent, ReactNode, PropsWithoutRef, RefAttributes } from 'react';
-import type { Changes as BaseChanges, Connection, Immutable, Value } from '@webkrafters/auto-immutable';
-import { FULL_STATE_SELECTOR } from './constants';
+import type { ComponentType, ForwardRefExoticComponent, MemoExoticComponent, NamedExoticComponent, PropsWithoutRef, RefAttributes } from 'react';
 export type { BaseType, ClearCommand, KeyType, MoveCommand, PushCommand, ReplaceCommand, SetCommand, SpliceCommand, TagCommand, TagType, UpdateStats, UpdatePayload, UpdatePayloadArray } from '@webkrafters/auto-immutable';
-export type State = Value;
-export type Listener<T extends State = {}> = (changes: Changes<T>, changedPathsTokens: Readonly<Array<Array<string>>>, netChanges: Readonly<T>, mayHaveChangesAt: (pathTokens: Array<string>) => boolean) => void;
-export type ObservableProvider<T extends State> = ForwardRefExoticComponent<ProviderProps<T> & RefAttributes<StoreRef<T>>>;
-export interface ProviderProps<T extends State> {
-    children?: ReactNode;
-    prehooks?: Prehooks<T>;
-    storage?: IStorage<T>;
-    value: PartialState<T>;
-}
+export type { ArraySelector, Changes, Channel, Data, FullStateSelector, IStorage, IStore, Listener, ObjectSelector, Prehooks, ProviderProps, SelectorMap, State, Store, StoreInternal, StoreRef, Stream, Text, Unsubscribe } from '@webkrafters/eagleeye';
+import { SelectorMap, State, Store } from '@webkrafters/eagleeye';
+export { CLEAR_TAG, DELETE_TAG, FULL_STATE_SELECTOR, MOVE_TAG, NULL_SELECTOR, PUSH_TAG, REPLACE_TAG, SET_TAG, SPLICE_TAG, Tag, } from '@webkrafters/eagleeye';
 export type ConnectProps<OWNPROPS extends OwnProps = IProps, STATE extends State = State, SELECTOR_MAP extends SelectorMap = SelectorMap> = {
     [K in keyof Store<STATE, SELECTOR_MAP>]: Store<STATE, SELECTOR_MAP>[K];
 } & Omit<OWNPROPS, "ref"> & RefAttributes<OWNPROPS["ref"]>;
@@ -21,68 +13,4 @@ export interface IProps {
     ref?: unknown;
 }
 export type OwnProps = IProps & Record<any, any>;
-export type Text = string | number;
-export type FullStateSelector = typeof FULL_STATE_SELECTOR;
-export type ObjectSelector = Record<Text, Text | FullStateSelector>;
-export type ArraySelector = Array<Text | FullStateSelector>;
-export type SelectorMap = ObjectSelector | ArraySelector | void;
-type ReplacePathSeps<P extends Text, T extends string> = P extends `${infer U}${T}${infer V}` ? ReplacePathSeps<`${U}.${V}`, T> : P;
-type TrimPathSep<P extends Text> = P extends `${infer U}]${never}` ? U : P;
-type NormalizePath<P extends Text> = TrimPathSep<ReplacePathSeps<ReplacePathSeps<ReplacePathSeps<P, ']['>, '].'>, '['>>;
-type Datum<P extends Text, S extends Record<Text, any> = State> = P extends `${infer K}.${infer P_1}` ? Datum<P_1, S[K]> : P extends '' ? S : any;
-type DataPoint<P extends Text, S extends State> = P extends FullStateSelector ? S : Datum<NormalizePath<P>, S>;
-export type Data<SELECTOR_MAP extends SelectorMap, STATE extends State = State> = (SELECTOR_MAP extends ObjectSelector ? {
-    [S_KEY in keyof SELECTOR_MAP]: DataPoint<SELECTOR_MAP[S_KEY], STATE>;
-} : SELECTOR_MAP extends ArraySelector ? {
-    [S_NUM: number]: DataPoint<SELECTOR_MAP[number], STATE>;
-} : Array<any>);
-export type Changes<T extends State = State> = BaseChanges<T>;
-export interface IStorage<T extends State = State> {
-    clone: (data: T) => T;
-    getItem: (key: string) => T;
-    removeItem: (key: string) => void;
-    setItem: (key: string, data: T) => void;
-}
-export type NonReactUsageReport = (...args: Array<unknown>) => void;
-export type PartialState<T extends State> = T extends Partial<infer U> ? T : Partial<T>;
-export interface Prehooks<T extends State = State> {
-    resetState?: (resetData: PartialState<T>, state: {
-        current: T;
-        original: T;
-    }) => boolean;
-    setState?: (newChanges: Changes<T>) => boolean;
-}
-export type Subscribe = <T extends State>(listener: Listener<T>) => Unsubscribe;
-export type Unsubscribe = (...args: Array<unknown>) => void;
-export interface IStore {
-    resetState: Function;
-    setState: Function;
-}
-export interface IStoreInternal extends IStore {
-    subscribe: Function;
-}
-export interface Store<T extends State, SELECTOR_MAP extends SelectorMap = SelectorMap> extends IStore {
-    data: Data<SELECTOR_MAP>;
-    resetState: (propertyPaths?: Array<string>) => void;
-    setState: (changes: Changes<T>) => void;
-}
-export interface StoreInternal<T extends State> extends IStoreInternal {
-    cache: Immutable<Partial<T>>;
-    resetState: (connection: Connection<T>, propertyPaths?: Array<string>) => void;
-    setState: (connection: Connection<T>, changes: Changes<T>) => void;
-    subscribe: Subscribe;
-}
-export interface StorePlaceholder extends IStoreInternal {
-    getState: NonReactUsageReport;
-    resetState: NonReactUsageReport;
-    setState: NonReactUsageReport;
-    subscribe: NonReactUsageReport;
-}
-export interface StoreRef<T extends State = State> extends StorePlaceholder {
-    getState: (propertyPaths?: Array<string>) => T;
-    resetState: (propertyPaths?: Array<string>) => void;
-    setState: (changes: Changes<T>) => void;
-    subscribe: Subscribe;
-}
-export { CLEAR_TAG, DELETE_TAG, FULL_STATE_SELECTOR, MOVE_TAG, NULL_SELECTOR, PUSH_TAG, REPLACE_TAG, SET_TAG, SPLICE_TAG, Tag, } from './constants';
-export { connect, createContext, ObservableContext, UsageError, useContext } from './main';
+export { createContext as createEagleEye } from './main';

package/dist/index.js

@@ -3,102 +3,72 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.useContext = exports.UsageError = exports.ObservableContext = exports.createContext = exports.connect = exports.Tag = exports.SPLICE_TAG = exports.SET_TAG = exports.REPLACE_TAG = exports.PUSH_TAG = exports.NULL_SELECTOR = exports.MOVE_TAG = exports.FULL_STATE_SELECTOR = exports.DELETE_TAG = exports.CLEAR_TAG = void 0;
-;
-;
-;
-;
-;
-;
-var constants_1 = require("./constants");
+exports.createEagleEye = exports.Tag = exports.SPLICE_TAG = exports.SET_TAG = exports.REPLACE_TAG = exports.PUSH_TAG = exports.NULL_SELECTOR = exports.MOVE_TAG = exports.FULL_STATE_SELECTOR = exports.DELETE_TAG = exports.CLEAR_TAG = void 0;
+var eagleeye_1 = require("@webkrafters/eagleeye");
 Object.defineProperty(exports, "CLEAR_TAG", {
   enumerable: true,
   get: function get() {
-    return constants_1.CLEAR_TAG;
+    return eagleeye_1.CLEAR_TAG;
   }
 });
 Object.defineProperty(exports, "DELETE_TAG", {
   enumerable: true,
   get: function get() {
-    return constants_1.DELETE_TAG;
+    return eagleeye_1.DELETE_TAG;
   }
 });
 Object.defineProperty(exports, "FULL_STATE_SELECTOR", {
   enumerable: true,
   get: function get() {
-    return constants_1.FULL_STATE_SELECTOR;
+    return eagleeye_1.FULL_STATE_SELECTOR;
   }
 });
 Object.defineProperty(exports, "MOVE_TAG", {
   enumerable: true,
   get: function get() {
-    return constants_1.MOVE_TAG;
+    return eagleeye_1.MOVE_TAG;
   }
 });
 Object.defineProperty(exports, "NULL_SELECTOR", {
   enumerable: true,
   get: function get() {
-    return constants_1.NULL_SELECTOR;
+    return eagleeye_1.NULL_SELECTOR;
   }
 });
 Object.defineProperty(exports, "PUSH_TAG", {
   enumerable: true,
   get: function get() {
-    return constants_1.PUSH_TAG;
+    return eagleeye_1.PUSH_TAG;
   }
 });
 Object.defineProperty(exports, "REPLACE_TAG", {
   enumerable: true,
   get: function get() {
-    return constants_1.REPLACE_TAG;
+    return eagleeye_1.REPLACE_TAG;
   }
 });
 Object.defineProperty(exports, "SET_TAG", {
   enumerable: true,
   get: function get() {
-    return constants_1.SET_TAG;
+    return eagleeye_1.SET_TAG;
   }
 });
 Object.defineProperty(exports, "SPLICE_TAG", {
   enumerable: true,
   get: function get() {
-    return constants_1.SPLICE_TAG;
+    return eagleeye_1.SPLICE_TAG;
   }
 });
 Object.defineProperty(exports, "Tag", {
   enumerable: true,
   get: function get() {
-    return constants_1.Tag;
+    return eagleeye_1.Tag;
   }
 });
 var main_1 = require("./main");
-Object.defineProperty(exports, "connect", {
-  enumerable: true,
-  get: function get() {
-    return main_1.connect;
-  }
-});
-Object.defineProperty(exports, "createContext", {
+Object.defineProperty(exports, "createEagleEye", {
   enumerable: true,
   get: function get() {
     return main_1.createContext;
   }
-});
-Object.defineProperty(exports, "ObservableContext", {
-  enumerable: true,
-  get: function get() {
-    return main_1.ObservableContext;
-  }
-});
-Object.defineProperty(exports, "UsageError", {
-  enumerable: true,
-  get: function get() {
-    return main_1.UsageError;
-  }
-});
-Object.defineProperty(exports, "useContext", {
-  enumerable: true,
-  get: function get() {
-    return main_1.useContext;
-  }
 });

package/dist/main/index.d.ts

@@ -1,22 +1,24 @@
 import type { ElementType, NamedExoticComponent } from 'react';
-import type { ConnectedComponent, ConnectProps, ExtractInjectedProps, IStoreInternal, ObservableProvider, SelectorMap, State, Store } from '..';
-import React from 'react';
-declare const __CTX_SYM__: unique symbol;
+import type { ConnectedComponent, ConnectProps, ExtractInjectedProps, SelectorMap, Store } from '..';
+import { AutoImmutable, IStorage, Prehooks, State } from "@webkrafters/eagleeye";
 export declare class ObservableContext<T extends State> {
-    private cxt;
-    private provider;
-    constructor();
-    get [__CTX_SYM__](): React.Context<IStoreInternal>;
-    get Consumer(): React.Consumer<IStoreInternal>;
-    get Provider(): ObservableProvider<T>;
+    private consumer;
+    constructor(value?: T, prehooks?: Prehooks<T>, storage?: IStorage<T>);
+    constructor(value?: AutoImmutable<T>, prehooks?: Prehooks<T>, storage?: IStorage<T>);
+    get cache(): AutoImmutable<T>;
+    get closed(): boolean;
+    get connect(): <S extends SelectorMap>(selectorMap?: S) => {
+        <P extends ExtractInjectedProps<T, S>>(WrappedComponent: ElementType<ConnectProps<P, T, S>>): ConnectedComponent<P>;
+        <P extends ExtractInjectedProps<T, S>>(WrappedComponent: NamedExoticComponent<ConnectProps<P, T, S>>): ConnectedComponent<P>;
+    };
+    get prehooks(): Prehooks<T>;
+    get storage(): IStorage<T>;
+    get store(): import("@webkrafters/eagleeye").StoreRef<T>;
+    get useStream(): <S extends SelectorMap>(selectorMap?: S) => Store<T, S>;
+    set prehooks(prehooks: Prehooks<T>);
+    set storage(storage: IStorage<T>);
+    private _connect;
+    dispose(): void;
 }
-export declare class UsageError extends Error {
-}
-export declare function connect<STATE extends State = State, SELECTOR_MAP extends SelectorMap = SelectorMap>(context: ObservableContext<STATE>, selectorMap?: SELECTOR_MAP): {
-    <P extends ExtractInjectedProps<STATE, SELECTOR_MAP>>(WrappedComponent: ElementType<ConnectProps<P, STATE, SELECTOR_MAP>>): ConnectedComponent<P>;
-    <P extends ExtractInjectedProps<STATE, SELECTOR_MAP>>(WrappedComponent: NamedExoticComponent<ConnectProps<P, STATE, SELECTOR_MAP>>): ConnectedComponent<P>;
-};
-export declare function createContext<T extends State = State>(): ObservableContext<T>;
-export declare function mkReadonly(v: any): any;
-export declare function useContext<STATE extends State, SELECTOR_MAP extends SelectorMap>(context: ObservableContext<STATE>, selectorMap?: SELECTOR_MAP): Store<STATE, SELECTOR_MAP>;
-export {};
+export declare function createContext<T extends State>(value?: T, prehooks?: Prehooks<T>, storage?: IStorage<T>): ObservableContext<T>;
+export declare function createContext<T extends State>(value?: AutoImmutable<T>, prehooks?: Prehooks<T>, storage?: IStorage<T>): ObservableContext<T>;