@cyysummer/projector 0.0.3 → 0.0.5

package/dist/index.js

@@ -1,6 +1,7 @@
 /**
-* @cyysummer/projector v0.0.2
+* @cyysummer/projector v0.0.5
 * (c) 2021-PRESENT Chris Liu
 * @license MIT
 **/
-import m from"on-change";import{set as d}from"lodash-es";import{withEvents as g}from"@cyysummer/core";var T=class extends g(){constructor(e){super();this._paused=!1;this._shadow=structuredClone(e)}record(e,r){this._paused||(d(this._shadow,e,r),this.emit("record",{next:this._shadow,patches:[{path:e,value:r}]}))}pause(){this._paused=!0}resume(){this._paused=!1}};import{get as p}from"lodash-es";var h=a=>{},l=class{constructor(t){this._strategy=t}chain(t){return async(e,r)=>{let c=s(r);for(let o of t)await o(e,{value:c})}}chainWith(t,e){return async(c,o)=>{let u=s(o),n=e(u);for(let i of t)await i(c,{value:n})}}create(t){return(e,r)=>{let c=s(r);return this._strategy.execute(e,t,c)}}createIf(t,e,r=h){return(c,o)=>{let u=s(o);return(t(u)?e:r)(c,{value:u})}}createIfRoot(t,e,r=h){return(c,o)=>(t(o.source)?e:r)(c,o)}createRoot(t,e){return(r,c)=>{let o=e(c.source);return this._strategy.execute(r,t,o)}}createForArray(t){return(e,r)=>{let c=r.path?p(r.source,r.path):r.value;if(c&&Array.isArray(c)&&c.length>0){let o=Object.keys(c[0]);return this._strategy.executeArray(e,t,o,c)}}}createForRaw(t,e){return(r,c)=>this._strategy.execute(r,t,e)}createWith(t,e){return(c,o)=>{let u=s(o),n=e(u);return this._strategy.execute(c,t,n)}}};function s(a){return a.source&&a.path?p(a.source,a.path):a.value}var y=class{constructor(t,e){this._schema=t;this._scheduler=e}project(t,...e){if(!this._schema)throw new Error("Schema not loaded");for(let r of e)this._dispatch(t,r)}_dispatch(t,e){let{path:r,value:c}=e,o=this._resolveEffect(r);o&&this._scheduler.enqueue({path:r.join("."),effect:o,ctx:{source:t,path:r,value:c}})}_resolveEffect(t){let e=this._schema;for(let r of t){if(!e)return null;e=e[r]}return typeof e=="function"?e:null}};var f=class{constructor(t=null){this._target=t;this._targetFactory=null}withTarget(t){return typeof t=="function"?this._targetFactory=t:this._target=t,this}checkTarget(){if(!this._target&&this._targetFactory&&(this._target=this._targetFactory()),!this._target)throw new Error("Scheduler: target is not set")}},S=class extends f{constructor(){super(...arguments);this._queue=new Map}enqueue(e){return this._queue.set(e.path,e),this}async flush(){this.checkTarget(),log.trace("BufferedScheduler: flushing");let e=[...this._queue.values()];this._queue.clear();for(let r of e){let{effect:c,ctx:o}=r,u=c(this._target,o);u instanceof Promise&&await u}}};function F(a){let t=new T(a);return[m(a,t.record.bind(t),{pathAsArray:!0}),t]}export{S as BufferedScheduler,l as EffectBuilder,y as Projector,T as Recorder,f as Scheduler,F as track};
+import E from"on-change";import{set as g}from"lodash-es";import{withEvents as I}from"@cyysummer/core";var i=class extends I(){constructor(e){super();this._paused=!1;this._shadow=structuredClone(e)}receive(e,r){if(this._paused)return;g(this._shadow,e,r);let c=[{path:e,value:r}];this.emit("record",{next:this._shadow,patches:c}),this._ensureProjector(),this._projector?.project(this._shadow,...c)}sendTo(e){typeof e=="function"?this._projectorFactory=e:this._projector=e}pause(){this._paused=!0}resume(){this._paused=!1}_ensureProjector(){!this._projector&&this._projectorFactory&&(this._projector=this._projectorFactory())}};import{get as d}from"lodash-es";var l=u=>{},p=class{constructor(t){this._strategy=t}chain(t){return async(e,r)=>{let c=n(r);for(let o of t)await o(e,{value:c})}}chainWith(t,e){return async(c,o)=>{let s=n(o),a=e(s);for(let f of t)await f(c,{value:a})}}create(t){return(e,r)=>{let c=n(r);return this._strategy.execute(e,t,c)}}createIf(t,e,r=l){return(c,o)=>{let s=n(o);return(t(s)?e:r)(c,{value:s})}}createIfRoot(t,e,r=l){return(c,o)=>(t(o.source)?e:r)(c,o)}createRoot(t,e){return(r,c)=>{let o=e(c.source);return this._strategy.execute(r,t,o)}}createForArray(t){return(e,r)=>{let c=r.path?d(r.source,r.path):r.value;if(c&&Array.isArray(c)&&c.length>0){let o=Object.keys(c[0]);return this._strategy.executeArray(e,t,o,c)}}}createForRaw(t,e){return(r,c)=>this._strategy.execute(r,t,e)}createWith(t,e){return(c,o)=>{let s=n(o),a=e(s);return this._strategy.execute(c,t,a)}}};function n(u){return u.source&&u.path?d(u.source,u.path):u.value}var h=class{constructor(t){this._schema=t;if(!t)throw new Error("Projector: Schema is required.")}project(t,...e){for(let r of e)this._dispatch(t,r)}_dispatch(t,e){let{path:r,value:c}=e,o=this._resolveEffect(r);o&&(this._ensureScheduler(),this._scheduler.enqueue({path:r.join("."),effect:o,ctx:{source:t,path:r,value:c}}))}_ensureScheduler(){if(!this._scheduler)throw new Error("Projector: no scheduler.")}_resolveEffect(t){let e=this._schema;for(let r of t){if(!e)return null;e=e[r]}return typeof e=="function"?e:null}},S=class extends h{constructor(t,e){super(t),this._scheduler=e}},y=class extends h{scheduleWith(t){return typeof t=="function"?this._schedulerFactory=t:this._scheduler=t,this}_ensureScheduler(){if(!this._scheduler&&this._schedulerFactory&&(this._scheduler=this._schedulerFactory()),!this._scheduler)throw new Error("Projector: no scheduler.")}};var T=class{constructor(t){this._target=t}withTarget(t){return typeof t=="function"?this._targetFactory=t:this._target=t,this}checkTarget(){if(!this._target&&this._targetFactory&&(this._target=this._targetFactory()),!this._target)throw new Error("Scheduler: target is not set")}},_=class extends T{constructor(){super(...arguments);this._queue=new Map}enqueue(e){return this._queue.set(e.path,e),this}async flush(){this.checkTarget(),log.trace("BufferedScheduler: flushing");let e=[...this._queue.values()];this._queue.clear();for(let r of e){let{effect:c,ctx:o}=r,s=c(this._target,o);s instanceof Promise&&await s}}};function C(u){let t=new i(u);return[E(u,t.receive.bind(t),{pathAsArray:!0}),t]}export{_ as BufferedScheduler,y as DynamicProjector,p as EffectBuilder,S as Projector,h as ProjectorBase,i as Recorder,T as Scheduler,C as track};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cyysummer/projector",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A powerful state projection library for creating anything.",
   "license": "MIT",
   "author": "Chris Liu",
   "files": [
-    "dist/**",
+    "dist/*.js",
     "types/**"
   ],
   "type": "module",

package/types/lib.d.ts

@@ -1,3 +1,6 @@
+/**
+ * A Schema defines how to project changes from a source object to a target object.
+ */
 // prettier-ignore
 type Schema<TSource, T = any> = TSource extends object ?
     Partial<{
@@ -12,9 +15,15 @@ type Schema<TSource, T = any> = TSource extends object ?
     // Else map T to effect.
     : Effect<TSource, T>;
 
+/**
+ * An effect defines how to project a value from source to target.
+ */
 // todo: Solve this `any`
 type Effect<TSource, TValue> = (target: any, ctx: IEffectContext<TSource, TValue>) => MaybePromise<void>;
 
+/**
+ * The context for an effect. It contains information about changes.
+ */
 interface IEffectContext<TSource, TValue> {
     /**
      * The source object.
@@ -32,9 +41,12 @@ interface IEffectContext<TSource, TValue> {
     value: TValue;
 }
 
-interface ITargetStrategy<TTarget> {
-    execute<T>(target: TTarget, at: string, value: T): MaybePromise<void>;
-    executeArray<T>(target: TTarget, at: string, keys: Partial<keyof T>[], rows: T[]): MaybePromise<void>;
+/**
+ * Strategy defines actual execution methods for projecting values to target.
+ */
+interface ITargetExecutionStrategy<TTarget, TLocation = any> {
+    execute<T>(target: TTarget, at: TLocation, value: T): MaybePromise<void>;
+    executeArray<T>(target: TTarget, at: TLocation, keys: Partial<keyof T>[], rows: T[]): MaybePromise<void>;
 }
 
 interface IProjector<TSource> {
@@ -71,11 +83,30 @@ declare const Recorder_base: Constructor<object> & (new (...args: any[]) => obje
  */
 declare class Recorder<TSource extends object> extends Recorder_base {
     private _paused;
+    private _projector?;
+    private _projectorFactory?;
     private _shadow;
     constructor(initial: TSource);
-    record(path: any[], value: any): void;
+    /**
+     * Receive changes from the tracked object.
+     * @param path
+     * @param value
+     * @returns
+     */
+    receive(path: any[], value: any): void;
+    /**
+     * Send changes to a projector.
+     * @param projector
+     */
+    sendTo(projector: IProjector<TSource>): void;
+    /**
+     * Send changes to a projector.
+     * @param factory
+     */
+    sendTo(factory: Func<IProjector<TSource>>): void;
     pause(): void;
     resume(): void;
+    private _ensureProjector;
 }
 
 /**
@@ -83,7 +114,7 @@ declare class Recorder<TSource extends object> extends Recorder_base {
  */
 declare class EffectBuilder<TTarget, TSource extends object> {
     private _strategy;
-    constructor(_strategy: ITargetStrategy<TTarget>);
+    constructor(_strategy: ITargetExecutionStrategy<TTarget>);
     /**
      * Call multiple effects in sequence.
      * @param effects Effects to call.
@@ -148,22 +179,32 @@ declare class EffectBuilder<TTarget, TSource extends object> {
     createWith<T, R>(at: string, customizer: Func1<T, R>): Effect<TSource, R>;
 }
 
-declare class Projector<TSource> implements IProjector<TSource> {
-    private _schema;
-    private _scheduler;
-    constructor(_schema: Schema<TSource>, _scheduler: IScheduler<any>);
+declare abstract class ProjectorBase<TSource> implements IProjector<TSource> {
+    protected _schema: Schema<TSource>;
+    protected _scheduler?: IScheduler<any>;
+    constructor(_schema: Schema<TSource>);
     project(next: TSource, ...patches: Patch[]): void;
-    private _dispatch;
-    private _resolveEffect;
+    protected _dispatch(next: TSource, patch: Patch): void;
+    protected _ensureScheduler(): void;
+    protected _resolveEffect(path: (string | symbol)[]): Effect<TSource, any> | null;
+}
+declare class Projector<TSource> extends ProjectorBase<TSource> {
+    constructor(_schema: Schema<TSource>, _scheduler: IScheduler<any>);
+}
+declare class DynamicProjector<TSource> extends ProjectorBase<TSource> {
+    private _schedulerFactory?;
+    scheduleWith(scheduler: IScheduler<any>): IProjector<TSource>;
+    scheduleWith(schedulerFactory: Func<IScheduler<any>>): IProjector<TSource>;
+    protected _ensureScheduler(): void;
 }
 
 /**
  * Scheduler abstract class, used to schedule projector effects.
  */
 declare abstract class Scheduler<TTarget> implements IScheduler<TTarget> {
-    protected _target: TTarget | null;
-    protected _targetFactory: Func<TTarget> | null;
-    constructor(_target?: TTarget | null);
+    protected _target?: TTarget | undefined;
+    protected _targetFactory?: Func<TTarget>;
+    constructor(_target?: TTarget | undefined);
     abstract enqueue(item: IScheduleItem<TTarget, any>): IScheduler<TTarget>;
     abstract flush(): MaybePromise<void>;
     withTarget(target: TTarget): IScheduler<TTarget>;
@@ -179,6 +220,11 @@ declare class BufferedScheduler<TTarget> extends Scheduler<TTarget> {
     flush(): Promise<void>;
 }
 
+/**
+ * Track changes to an object.
+ * @param initial Source object to track. This must the raw object, not reactive-enabled object.
+ * @returns A tuple of the tracked object and a recorder.
+ */
 declare function track<TSource extends object>(initial: TSource): [TSource, Recorder<TSource>];
 
-export { BufferedScheduler, EffectBuilder, Projector, Recorder, Scheduler, track };
+export { BufferedScheduler, DynamicProjector, EffectBuilder, Projector, ProjectorBase, Recorder, Scheduler, track };

package/types/types.d.ts

@@ -1,3 +1,6 @@
+/**
+ * A Schema defines how to project changes from a source object to a target object.
+ */
 // prettier-ignore
 export type Schema<TSource, T = any> = TSource extends object ?
     Partial<{
@@ -12,9 +15,15 @@ export type Schema<TSource, T = any> = TSource extends object ?
     // Else map T to effect.
     : Effect<TSource, T>;
 
+/**
+ * An effect defines how to project a value from source to target.
+ */
 // todo: Solve this `any`
 export type Effect<TSource, TValue> = (target: any, ctx: IEffectContext<TSource, TValue>) => MaybePromise<void>;
 
+/**
+ * The context for an effect. It contains information about changes.
+ */
 export interface IEffectContext<TSource, TValue> {
     /**
      * The source object.
@@ -32,9 +41,12 @@ export interface IEffectContext<TSource, TValue> {
     value: TValue;
 }
 
-export interface ITargetStrategy<TTarget> {
-    execute<T>(target: TTarget, at: string, value: T): MaybePromise<void>;
-    executeArray<T>(target: TTarget, at: string, keys: Partial<keyof T>[], rows: T[]): MaybePromise<void>;
+/**
+ * Strategy defines actual execution methods for projecting values to target.
+ */
+export interface ITargetExecutionStrategy<TTarget, TLocation = any> {
+    execute<T>(target: TTarget, at: TLocation, value: T): MaybePromise<void>;
+    executeArray<T>(target: TTarget, at: TLocation, keys: Partial<keyof T>[], rows: T[]): MaybePromise<void>;
 }
 
 export interface IProjector<TSource> {