@webkrafters/eagleeye 1.0.0-beta.0

package/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+	<img alt="Eagle Eye" height="150px" src="logo.png" width="250px" />
+</p>
+<p align="center">
+	<a href="https://typescriptlang.org">
+		<img alt="TypeScript" src="https://badgen.net/badge/icon/typescript?icon=typescript&label">
+	</a>
+	<a href="https://github.com/webKrafters/eagleeye.js/actions">
+		<img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/webKrafters/eagleeye.js/test.yml">
+	</a>
+	<a href="https://coveralls.io/github/webKrafters/eagleeye.js">
+		<img alt="coverage" src="https://img.shields.io/coveralls/github/webKrafters/eagleeye.js">
+	</a>
+	<img alt="NPM" src="https://img.shields.io/npm/l/@webkrafters/eagleeye.js">
+	<img alt="Maintenance" src="https://img.shields.io/maintenance/yes/2032">
+	<img alt="build size" src="https://img.shields.io/bundlephobia/minzip/@webkrafters/eagleeye.js?label=bundle%20size">
+	<a href="https://www.npmjs.com/package/@webKrafters/eagleeye.js">
+		<img alt="Downloads" src="https://img.shields.io/npm/dt/@webkrafters/eagleeye.js.svg">
+	</a>
+	<img alt="GitHub package.json version" src="https://img.shields.io/github/package-json/v/webKrafters/eagleeye.js">
+</p>
+
+# Eagle Eye.
+
+**Name:** Eagle Eye.
+
+**Install:**\
+npm install --save @webkrafters/eagleeye
+
+## Usage:
+### Create (the FP way).
+```tsx
+import { createEagleEye } from '@webkrafters/eagleeye';
+const context = createEagleEye({
+	prehooks?: Prehooks<T>,
+	storage?: Storage<T>,
+	value?: T|AutoImmutable<T>
+});
+```
+### Create (the OOP way).
+```tsx
+import { EagleEyeContext } from '@webkrafters/eagleeye';
+const context = new EagleEyeContext<T>(
+	T?|AutoImmutable<T>?,
+	Prehooks<T>?,
+	Storage<T>?
+);
+```
+
+### 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 );
+```
+
+### Connecting to context stream.
+A context stream allows for a client to set up automatic update to to be automatically pushed to it whenever its slice of state changes.
+```tsx
+const useStream = context.stream;
+// joining the stream twice
+// for more on selectorMap - https://eagleeye.js.org/concepts/selector-map/
+const streamer1 = useStream(SelectorMap?);
+const streamer2 = useStream(SelectorMap?);
+// check whether a streamer still defunct or still active
+if( streamer1.closed ) { ... };
+// access the current data value monitored by this streamer
+console.log( 'data', streamer1.data );
+// access the streamer current lifecycle
+console.log( 'life cycle', streamer1.phase );
+// check if the streamer is streaming
+if( streamer1.streaming ) { ... };
+// change a streamer's selector map 
+streamer1.seletorMap = SelectorMap<T>?;
+// add listener to a streamer to react to live updates to selected data.
+streamer1.addListener( 'data-changed', listener );
+// be notified of a streamer's exist from streaming.
+streamer1.addListener( 'stream-ending', listener );
+// remove listener from a streamer activities
+streamer1.removeListener( 'data-changed'|'stream-ending', listener );
+// https://eagleeye.js.org/concepts/store/resetstate/
+streamer1.resetState( Array<string>? ); // changes are context-wide
+// https://eagleeye.js.org/concepts/store/setstate/
+streamer1.setState( Changes<T> ); // changes are context-wide
+// exit streamer from streaming
+streamer1.endStream();
+```
+
+### 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 = storage<T>?;
+```
+
+## Notable Mentions:
+<ul>
+	<li>Facilitates sharing of underlying immutable data structure among multiple applications</li>
+	<li>Update-friendly Auto-immutable bearing context. See <a href="https://eagleeye.js.org/concepts/store/setstate"><code>store.setState</code></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 automatically notifying subscribing or stream (<a href="https://eagleeye.js.org/concepts/client">clients</a>) on context state changes.</li>
+	<li> Subscribers decide which exact context state properties' changes to monitor.</li>
+</ul>
+
+## Please see more documentation here:
+**[eagleeye.js.org](https://eagleeye.js.org)**
+
+# License
+
+GPLv3

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export { CLEAR_TAG, DELETE_TAG, GLOBAL_SELECTOR, MOVE_TAG, NULL_SELECTOR, PUSH_TAG, REPLACE_TAG, SET_TAG, SPLICE_TAG, Tag } from '@webkrafters/auto-immutable';
+export declare const FULL_STATE_SELECTOR = "@@STATE";

package/dist/constants.js

@@ -0,0 +1,68 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FULL_STATE_SELECTOR = exports.Tag = exports.SPLICE_TAG = exports.SET_TAG = exports.REPLACE_TAG = exports.PUSH_TAG = exports.NULL_SELECTOR = exports.MOVE_TAG = exports.GLOBAL_SELECTOR = exports.DELETE_TAG = exports.CLEAR_TAG = void 0;
+var auto_immutable_1 = require("@webkrafters/auto-immutable");
+Object.defineProperty(exports, "CLEAR_TAG", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.CLEAR_TAG;
+  }
+});
+Object.defineProperty(exports, "DELETE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.DELETE_TAG;
+  }
+});
+Object.defineProperty(exports, "GLOBAL_SELECTOR", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.GLOBAL_SELECTOR;
+  }
+});
+Object.defineProperty(exports, "MOVE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.MOVE_TAG;
+  }
+});
+Object.defineProperty(exports, "NULL_SELECTOR", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.NULL_SELECTOR;
+  }
+});
+Object.defineProperty(exports, "PUSH_TAG", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.PUSH_TAG;
+  }
+});
+Object.defineProperty(exports, "REPLACE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.REPLACE_TAG;
+  }
+});
+Object.defineProperty(exports, "SET_TAG", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.SET_TAG;
+  }
+});
+Object.defineProperty(exports, "SPLICE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.SPLICE_TAG;
+  }
+});
+Object.defineProperty(exports, "Tag", {
+  enumerable: true,
+  get: function get() {
+    return auto_immutable_1.Tag;
+  }
+});
+exports.FULL_STATE_SELECTOR = '@@STATE';

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import type { Changes as BaseChanges, Immutable as AutoImmutable, Value } from '@webkrafters/auto-immutable';
+import { FULL_STATE_SELECTOR } from './constants';
+import { createEagleEye, Streamer } from './main';
+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 ShutdownMonitor = (reason: ShutdownReason) => void;
+export type Listener = <T extends State>(changes: Changes<T>, changedPathsTokens: Readonly<Array<Array<string>>>, netChanges: Readonly<T>, mayHaveChangesAt: (pathTokens: Array<string>) => boolean) => void;
+export interface ContextInfra<T extends State> {
+    prehooks?: Prehooks<T>;
+    storage?: IStorage<T>;
+}
+export interface RawProviderProps<T extends State> extends ContextInfra<T> {
+    value?: T;
+}
+export interface ProviderProps<T extends State> extends ContextInfra<T> {
+    value?: AutoImmutable<T>;
+}
+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 void ? {} : 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>;
+interface StorageGetter<T extends State = State> {
+    (key: null): T;
+    (key: string): T;
+}
+interface StorageDeleteFn {
+    (key: null): void;
+    (key: string): void;
+}
+interface StorageSetter<T extends State = State> {
+    (key: null, data: T): void;
+    (key: string, data: T): void;
+}
+export interface IStorage<T extends State = State> {
+    clone: (data: T) => T;
+    getItem: StorageGetter<T>;
+    removeItem: StorageDeleteFn;
+    setItem: StorageSetter<T>;
+}
+export interface CurrentStorage<T extends State> extends IStorage<T> {
+    isKeyRequired?: boolean;
+}
+export interface Prehooks<T extends State = State> {
+    resetState?: (resetData: Partial<T>, state: {
+        current: T;
+        original: T;
+    }) => boolean;
+    setState?: (newChanges: Changes<T>) => boolean;
+}
+export type Unsubscribe = (...args: Array<unknown>) => void;
+export declare const enum Phase {
+    UN_OPENED = -1,
+    CLOSED = 0,
+    OPENED = 1,
+    CLOSING = 2
+}
+export declare const enum ShutdownReason {
+    CACHE = "CACHE DATA SHUTDOWN",
+    CONTEXT = "CONTEXT-WIDE SHUTDOWN",
+    LOCAL = "CURRENT STORE INITIATED SHUTDOWN"
+}
+export interface IStore<T extends State = State> {
+    resetState: (propertyPaths?: Array<string>) => void;
+    setState: (changes: Changes<T>) => void;
+}
+export interface Store<T extends State = State, SELECTOR_MAP extends SelectorMap = SelectorMap> extends IStore<T> {
+    data: Data<SELECTOR_MAP>;
+}
+export interface StoreRef<T extends State = State> extends IStore<T> {
+    getState: (propertyPaths?: Array<string>) => T;
+    subscribe: {
+        (eventType: "closing", listener: ShutdownMonitor): Unsubscribe;
+        (eventType: "data-updated", listener: Listener): Unsubscribe;
+    };
+}
+export interface StoreInternal<T extends State = State> extends StoreRef<T> {
+    close: () => void;
+    closed: boolean;
+}
+export interface BaseStream<T extends State = State> {
+    <S extends SelectorMap>(selectorMap?: S): Streamer<T, S>;
+}
+export interface Stream<T extends State = State> extends BaseStream<T> {
+    <S extends SelectorMap>(selectorMap?: S): Store<T, S>;
+}
+export { CLEAR_TAG, DELETE_TAG, FULL_STATE_SELECTOR, MOVE_TAG, NULL_SELECTOR, PUSH_TAG, REPLACE_TAG, SET_TAG, SPLICE_TAG, Tag, } from './constants';
+export { createEagleEye, EagleEyeContext, Streamer } from './main';
+export default createEagleEye;

package/dist/index.js

@@ -0,0 +1,108 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Streamer = exports.EagleEyeContext = 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 = exports.ShutdownReason = exports.Phase = void 0;
+var main_1 = require("./main");
+;
+;
+;
+;
+var Phase;
+(function (Phase) {
+  Phase[Phase["UN_OPENED"] = -1] = "UN_OPENED";
+  Phase[Phase["CLOSED"] = 0] = "CLOSED";
+  Phase[Phase["OPENED"] = 1] = "OPENED";
+  Phase[Phase["CLOSING"] = 2] = "CLOSING";
+})(Phase || (exports.Phase = Phase = {}));
+;
+var ShutdownReason;
+(function (ShutdownReason) {
+  ShutdownReason["CACHE"] = "CACHE DATA SHUTDOWN";
+  ShutdownReason["CONTEXT"] = "CONTEXT-WIDE SHUTDOWN";
+  ShutdownReason["LOCAL"] = "CURRENT STORE INITIATED SHUTDOWN";
+})(ShutdownReason || (exports.ShutdownReason = ShutdownReason = {}));
+;
+;
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "CLEAR_TAG", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.CLEAR_TAG;
+  }
+});
+Object.defineProperty(exports, "DELETE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.DELETE_TAG;
+  }
+});
+Object.defineProperty(exports, "FULL_STATE_SELECTOR", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.FULL_STATE_SELECTOR;
+  }
+});
+Object.defineProperty(exports, "MOVE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.MOVE_TAG;
+  }
+});
+Object.defineProperty(exports, "NULL_SELECTOR", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.NULL_SELECTOR;
+  }
+});
+Object.defineProperty(exports, "PUSH_TAG", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.PUSH_TAG;
+  }
+});
+Object.defineProperty(exports, "REPLACE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.REPLACE_TAG;
+  }
+});
+Object.defineProperty(exports, "SET_TAG", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.SET_TAG;
+  }
+});
+Object.defineProperty(exports, "SPLICE_TAG", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.SPLICE_TAG;
+  }
+});
+Object.defineProperty(exports, "Tag", {
+  enumerable: true,
+  get: function get() {
+    return constants_1.Tag;
+  }
+});
+var main_2 = require("./main");
+Object.defineProperty(exports, "createEagleEye", {
+  enumerable: true,
+  get: function get() {
+    return main_2.createEagleEye;
+  }
+});
+Object.defineProperty(exports, "EagleEyeContext", {
+  enumerable: true,
+  get: function get() {
+    return main_2.EagleEyeContext;
+  }
+});
+Object.defineProperty(exports, "Streamer", {
+  enumerable: true,
+  get: function get() {
+    return main_2.Streamer;
+  }
+});
+exports["default"] = main_1.createEagleEye;

package/dist/main/index.d.ts

@@ -0,0 +1,78 @@
+import type { Connection } from '@webkrafters/auto-immutable';
+import type { BaseStream, Changes, Data, IStorage, Listener, Prehooks, ProviderProps, RawProviderProps, SelectorMap, ShutdownMonitor, State, Store, StoreInternal, StoreRef, Unsubscribe } from '..';
+import AutoImmutable from '@webkrafters/auto-immutable';
+import { Phase, ShutdownReason } from '..';
+export declare const deps: {
+    createStorageKey: () => string;
+};
+export declare const ACCESS_SYM: unique symbol;
+export declare class Streamer<T extends State = State, S extends SelectorMap = SelectorMap> implements Store<T, S> {
+    private _context;
+    private _internalStore;
+    private _data;
+    private eventMap;
+    private _phase;
+    private _selectorMap;
+    private _unsubClosing;
+    private _unsubscribe;
+    constructor(context: EagleEyeContext<T>, selectorMap?: S);
+    get closed(): boolean;
+    get data(): Data<S, T>;
+    get phase(): Phase;
+    get streaming(): boolean;
+    set selectorMap(selectorMap: S);
+    addListener(eventType: 'stream-ending', listener: ShutdownMonitor): void;
+    addListener(eventType: 'data-changed', listener: () => void): void;
+    endStream(): void;
+    removeListener(eventType: 'stream-ending', listener: ShutdownMonitor): void;
+    removeListener(eventType: 'data-changed', listener: () => void): void;
+    resetState(propertyPaths?: string[]): void;
+    setState(changes: Changes<T>): void;
+    protected subscribe(): void;
+    protected unsubscribe(): void;
+    private get _renderKeys();
+    private _dataSourceListener;
+    private _integrateSelectors;
+    private _reclaim;
+    private _refreshDataRef;
+    private _setupInternalStore;
+    private _updateData;
+    private _updateInternalStore;
+}
+export declare class EagleEyeContext<T extends State = State> {
+    private _cache;
+    private _cacheCloseMonitor;
+    private _prehooks;
+    private _storage;
+    private _store;
+    private _storeRef;
+    private eventMap;
+    private inchoateValue;
+    private storageKey;
+    protected _stream: BaseStream<T>;
+    constructor(value?: AutoImmutable<T>, prehooks?: Prehooks<T>, storage?: IStorage<T>);
+    constructor(value?: T, prehooks?: Prehooks<T>, storage?: IStorage<T>);
+    get cache(): AutoImmutable<T>;
+    get closed(): boolean;
+    get prehooks(): Prehooks<T>;
+    get storage(): IStorage<T>;
+    get store(): StoreRef<T>;
+    get stream(): BaseStream<T>;
+    set prehooks(prehooks: Prehooks<T>);
+    set storage(storage: IStorage<T>);
+    createInternalStore(access?: Symbol): StoreInternal<T>;
+    dispose(): void;
+    protected createUpdateEmitterFor(changes: Changes<T>): (netChanges: Readonly<Partial<T>>, changedPathsTokens: Array<Array<string>>) => void;
+    protected disconnectInternalStore(connection: Connection<T>): void;
+    protected getState(connection: Connection<T>, propertyPaths: Array<string>): Readonly<Partial<T>>;
+    protected notifyClosing(reason: ShutdownReason): void;
+    protected resetState(connection: Connection<T>, propertyPaths: Array<string>): void;
+    protected setState(connection: Connection<T>, changes: Changes<T>): void;
+    protected subscribe(eventType: 'closing', listener: ShutdownMonitor): Unsubscribe;
+    protected subscribe(eventType: 'data-updated', listener: Listener): Unsubscribe;
+    private _createInternalStore;
+    private _reclaim;
+}
+export declare function createEagleEye<T extends State = State>(props?: RawProviderProps<T>): EagleEyeContext<T>;
+export declare function createEagleEye<T extends State = State>(props?: ProviderProps<T>): EagleEyeContext<T>;
+export declare function mkReadonly(v: any): any;