entropic-bond 1.48.1 → 1.50.0

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './observable/observable'
+export * from './persistent/entropic-component'
+export * from './persistent/persistent'
+export * from './store/data-source'
+export * from './store/json-data-source'
+export * from './store/store'
+export * from './store/model'
+export * from './types/utility-types'
+export * from './cloud-storage/cloud-storage'
+export * from './cloud-storage/mock-cloud-storage'
+export * from './cloud-storage/stored-file'
+export * from './auth/auth'
+export * from './auth/user-auth-types'
+export * from './auth/auth-mock'
+export * from './cloud-functions/cloud-functions'
+export * from './cloud-functions/cloud-functions-mock'
+export * from './server-auth/server-auth'
+export * from './server-auth/server-auth-mock'
+export * from './utils/utils'

package/src/observable/observable.spec.ts

@@ -0,0 +1,105 @@
+import {Observable} from './observable'
+
+class ObserverTest {
+	public changed: boolean = true
+	userChanged() {
+		this.changed = true
+	}
+}
+
+interface MockEvent {
+	[ idx: string ]: any
+}
+
+describe('observer', () => {
+	let observable: Observable<MockEvent | void>
+
+	beforeEach(()=>{
+		observable = new Observable<MockEvent | void>()
+	})
+
+	it('should subscribe ', () => {
+		const mockObserver = new ObserverTest();
+		const changedSpy = vi.spyOn( mockObserver, 'userChanged' )
+		
+		observable.subscribe( ()=>mockObserver.userChanged() )
+		observable.notify()
+		
+		expect( changedSpy ).toBeCalledTimes(1)
+	})
+	
+	it('should notify', ()=>{
+		const myCallback = vi.fn()
+
+		observable.subscribe( myCallback )
+		observable.notify()
+
+		expect( myCallback ).toHaveBeenCalledTimes(1)
+	})
+
+	it('should notify all subscribers', () => {
+		const callbackOne = vi.fn()
+		const callbackTwo = vi.fn()
+		const callbackThree = vi.fn()
+		observable.subscribe(callbackOne)
+		observable.subscribe(callbackTwo)
+		observable.subscribe(callbackThree)
+		
+		observable.notify()
+
+		expect(callbackOne).toHaveBeenCalledTimes(1)
+		expect(callbackTwo).toHaveBeenCalledTimes(1)
+		expect(callbackThree).toHaveBeenCalledTimes(1)
+	})
+
+	it( 'should notify with event', ()=>{
+		const myCallback = vi.fn()
+		const obj: MockEvent = {name: 'Juan'};
+
+		observable.subscribe( myCallback )
+		observable.notify(obj)
+
+		expect( myCallback ).toHaveBeenCalledWith( obj )
+	})
+
+	it('should not notify removed listeners', ()=>{
+		const callbackOne = vi.fn()
+		const callbackTwo = vi.fn()
+		const callbackThree = vi.fn()
+		observable.subscribe(callbackOne)
+		observable.subscribe(callbackTwo)
+		observable.subscribe(callbackThree)
+		
+		observable.notify()
+
+		expect(callbackOne).toHaveBeenCalledTimes(1)
+		expect(callbackTwo).toHaveBeenCalledTimes(1)
+		expect(callbackThree).toHaveBeenCalledTimes(1)
+
+		observable.unsubscribe( callbackThree )
+
+		observable.notify()
+
+		expect(callbackOne).toHaveBeenCalledTimes(2)
+		expect(callbackTwo).toHaveBeenCalledTimes(2)
+		expect(callbackThree).toHaveBeenCalledTimes(1)
+	})
+
+	it( 'should return an unsubscribe function on subscribe', ()=>{
+		const cb = vi.fn()
+		const unsubscriber = observable.subscribe( cb )	
+		unsubscriber()
+
+		observable.notify()
+		expect( cb ).not.toHaveBeenCalled()
+	})
+	
+	it( 'should return the number of subscribers', ()=>{
+		const cb = vi.fn()
+		observable.subscribe( cb )
+		observable.subscribe( cb )
+		observable.subscribe( vi.fn() )
+
+		expect( observable.subscribersCount ).toBe( 2 )
+	})
+})

package/src/observable/observable.ts

@@ -0,0 +1,67 @@
+export type Callback<T> = ( event: T ) => void
+export type Unsubscriber = ()=>void
+
+/**
+ * Implements the Observer pattern.
+ * The Observable class is used to notify a list of subscribers when an event occurs.
+ * The subscribers are callback functions that are called when the event occurs.
+ * The event is passed as a parameter to the callback function.
+ * @example
+ * // Create an observable
+ * const observable = new Observable<number>()
+ * // Subscribe a listener
+ * const unsubscribe = observable.subscribe( event => console.log( event ) )
+ * // Notify the subscribers
+ * observable.notify( 1 )
+ * // Unsubscribe the listener
+ * unsubscribe()
+ */
+export class Observable<T> {
+
+	/**
+	 * Subscribes a listener callback function. On every notification, 
+	 * the listener callback will be called with an event as a parameter if sent.
+	 * 
+	 * @param callback the listener callback
+	 * @returns a function to unsubscribe the listener from further notifications
+	 */
+	 subscribe( callback: Callback<T> ): Unsubscriber {
+		this.subscribers.add(callback)
+		return ()=>this.unsubscribe( callback )
+	}
+
+	/**
+	 * Removes the callback from the notification list.
+	 * 
+	 * @param listenerCallback the listener callback to remove
+	 */
+	unsubscribe( callback: Callback<T> ) {
+		this.subscribers.delete( callback )
+	}
+
+	/**
+	 * Notifies all the subscribers with the event passed as parameter.
+	 * 
+	 * @param event the event passed to all subscribers.
+	 */
+	notify( event?: T ) {
+		this.subscribers.forEach(subs => subs(event!))
+	}
+
+	/**
+	 * Returns the number of subscribers.
+	 * 
+	 * @returns the number of subscribers
+	 * @example
+	 * const observable = new Observable<number>()
+	 * observable.subscribe( event => console.log( event ) )
+	 * observable.subscribe( event => console.log( event ) )
+	 * observable.subscribe( event => console.log( event ) )
+	 * console.log( observable.subscribersCount ) // 3
+	 */
+	get subscribersCount() {
+		return this.subscribers.size
+	}
+
+	private subscribers: Set<Callback<T>> = new Set()
+}

package/src/persistent/entropic-component.spec.ts

@@ -0,0 +1,143 @@
+import { CompareFunction, EntropicComponent } from './entropic-component'
+
+class Character extends EntropicComponent {
+	setName( value: string ) {
+		this.changeProp( 'name', value )
+		return this
+	}
+
+	get name() {
+		return this._name
+	}
+
+	pushFriend( name: string, isUnique?: CompareFunction<Character> ) {
+		return this.pushAndNotify<Character>( 'friends', name, isUnique )
+	}
+
+	removeFriend( name: string, isEqual: CompareFunction<Character> ) {
+		return this.removeAndNotify<Character>( 'friends', name, isEqual )
+	}
+
+	get friends(): readonly string[] {
+		return this._friends
+	}
+
+	private _friends: string[] = []
+	private _name: string = ''
+}
+
+describe('Observable Persistent', ()=>{
+	let hero: Character
+
+	beforeEach(()=>{
+		hero = new Character()
+	})
+	
+	it( 'should change properties', ()=>{
+		hero.setName( 'Rogue I' )
+
+		expect( hero.name ).toEqual( 'Rogue I' )
+	})
+
+	it( 'should notify on change', ()=>{
+		const changed = vi.fn()
+		hero.onChange( changed )
+
+		hero.setName( 'Rogue I' )
+
+		expect( changed ).toHaveBeenCalledWith({ name: 'Rogue I' })
+	})
+
+	it( 'should return a unsubscribe function on subscription', ()=>{
+		const changed = vi.fn()
+
+		const unsubscribe = hero.onChange( changed )
+		unsubscribe()
+		hero.setName( 'Rogue II' )
+
+		expect( changed ).not.toHaveBeenCalled()
+	})
+
+	describe( 'Array Props', ()=>{
+		let spy = vi.fn()
+	
+		beforeEach(()=>{
+			hero.onChange( spy )
+		})
+	
+		afterEach(()=>{
+			hero.removeOnChange( spy )
+			spy.mockClear()
+		})
+	
+		it( 'should insert element in array member and notify', ()=>{
+			const res = hero.pushFriend( 'John' )
+			
+			expect( res ).toEqual( 'John' )
+			expect( hero.friends ).toContain( 'John' )
+			expect( spy ).toHaveBeenCalledTimes(1)
+			expect( spy ).toHaveBeenCalledWith({ friends: ['John'] })
+		})
+
+		it( 'should insert different elements in array member', ()=>{
+			expect( hero.pushFriend( 'John' ) ).toBeDefined()
+			expect( hero.pushFriend( 'Jaume' ) ).toBeDefined()
+			
+			expect( hero.friends ).toContain( 'John' )
+			expect( hero.friends ).toContain( 'Jaume' )
+			expect( spy ).toHaveBeenCalledTimes(2)
+		})
+
+		it( 'should insert different elements in array member with check function', ()=>{
+			const isUnique = ( a: string, b: string ) => a!==b
+			
+			expect( hero.pushFriend( 'John', isUnique ) ).toBeDefined()
+			expect( hero.pushFriend( 'Jaume', isUnique ) ).toBeDefined()
+			
+			expect( hero.friends ).toContain( 'John' )
+			expect( hero.friends ).toContain( 'Jaume' )
+			expect( spy ).toHaveBeenCalledTimes(2)
+		})
+
+		it( 'should not insert repeated elements in array member with check function', ()=>{
+			const isUnique = ( a: string, b: string ) => a!==b
+			
+			expect( hero.pushFriend( 'John', isUnique ) ).toBeDefined()
+			expect( hero.pushFriend( 'John', isUnique ) ).not.toBeDefined()
+			
+			expect( hero.friends ).toContain( 'John' )
+			expect( hero.friends ).toHaveLength( 1 )
+			expect( spy ).toHaveBeenCalledTimes( 1 )
+		})
+		
+		it( 'should remove an element from array member and notify', ()=>{
+			const isEqual = ( a: string, b: string ) => a===b
+			hero.pushFriend( 'John' )
+			hero.pushFriend( 'Jaume' )
+			spy.mockReset()
+			expect( hero.friends ).toHaveLength( 2 )
+
+			const res = hero.removeFriend( 'John', isEqual )
+			expect( res ).toEqual( 'John' )
+			expect( hero.friends ).not.toContain( 'John' )
+			expect( hero.friends ).toContain( 'Jaume' )
+			expect( spy ).toHaveBeenCalledTimes(1)
+			expect( spy ).toHaveBeenCalledWith({ friends: ['Jaume'] })
+		})
+		
+		it( 'should not notify on element not removed', ()=>{
+			const isEqual = ( a: string, b: string ) => a===b
+			hero.pushFriend( 'John' )
+			hero.pushFriend( 'Jaume' )
+			spy.mockReset()
+			expect( hero.friends ).toHaveLength( 2 )
+
+			const res = hero.removeFriend( 'Nobody', isEqual )
+			expect( res ).toBeUndefined()
+			expect( hero.friends ).toContain( 'John' )
+			expect( hero.friends ).toContain( 'Jaume' )
+			expect( spy ).not.toHaveBeenCalled()
+		})
+		
+	})
+})

package/src/persistent/entropic-component.ts

@@ -0,0 +1,135 @@
+import { Callback, Observable, Unsubscriber } from '../observable/observable';
+import { ClassArrayPropNames, ClassProps, Elements } from '../types/utility-types';
+import { Persistent } from './persistent';
+
+export type PropChangeEvent<T> = Partial<ClassProps<T>>
+export type PropChangeCallback<T> = Callback<PropChangeEvent<T>>
+type ArrayPropsElem<T> = Elements<T[ClassArrayPropNames<T>]>
+export type CompareFunction<T> = ( a: ArrayPropsElem<T>, b: ArrayPropsElem<T> )=>boolean
+
+/**
+ * Derived classes from EntropicComponent will have the ability to notify 
+ * property changes by calling one of the provided notification methods.
+ * It extends Persistent class therefore EntropicComponent children will have
+ * persistance through the Entropic Bond persistence mechanism
+ */
+export class EntropicComponent extends Persistent {
+
+	/**
+	 * Subscribes a listener callback function. Every time a property is changed, 
+	 * the listener callback will be called with the property change event.
+	 * 
+	 * @param listenerCallback the listener callback
+	 * @returns a function to unsubscribe the listener from further notifications
+	 */
+	onChange( listenerCallback: PropChangeCallback<this> ): Unsubscriber {
+		return this._onChange.subscribe( listenerCallback )
+	}
+
+	/**
+	 * Removes the listener callback subscrition from the notifications.
+	 * 
+	 * @param listenerCallback the listener callback to remove
+	 */
+	removeOnChange( listenerCallback: PropChangeCallback<this> ) {
+		this._onChange.unsubscribe( listenerCallback )
+	}
+
+	/**
+	 * Changes the value of the property and notifies the subscribers about the change.
+	 * This is a helper method that can be used in the property setter.
+	 * 
+	 * @param propName the name of the property to be changed
+	 * @param value the new value for the property
+	 * @returns true in case the property has been effectively changed, false otherwise
+	 */
+	protected changeProp<P extends keyof this>( propName: P, value: this[ P ] ): boolean {
+		const pName = '_' + String( propName );
+
+		if ( this[ pName ] !== value ) {
+			this[ pName ] = value;
+			this._onChange.notify({ [ propName ]: value });
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Notifies the subscribers a property or group of properties change.
+	 * This is a helper function to be used when you want to notify property changes.
+	 * 
+	 * @param event the event with the changed properties
+	 */
+	protected notify<T extends EntropicComponent>( event: PropChangeEvent<T> ) {
+		this._onChange.notify(event)
+	}
+
+	/**
+	 * Inserts a new element in an arbitrary array property of this class and 
+	 * fires a change event if successfully inserted. To avoid repeated elements
+	 * to be inserted, you can pass a function that checks for inequity.
+	 * 
+	 * @param arrayPropName the name of the array property of this class where you
+	 * 											want to insert the	new element.
+	 * @param element the element to be inserted
+	 * @param isUnique a function that checks for inequity of the two elements 
+	 * 									passed as parameter. If the returned value is true, the 
+	 * 									value will be	pushed into the array. When the function is 
+	 * 									not provided, the element will be inserted regardless it is
+	 * 									already in the array.
+	 * @returns the inserted element or undefined if the element was not inserted.
+	 */
+	protected pushAndNotify<T extends EntropicComponent>( 
+		arrayPropName: ClassArrayPropNames<T>, 
+		element: ArrayPropsElem<T>, 
+		isUnique?: CompareFunction<T> 
+	): ArrayPropsElem<T> | undefined {
+
+		const pName = '_' + String( arrayPropName );
+		const alreadyIn = isUnique && this[ pName ].find( 
+			( item: ArrayPropsElem<T> ) => !isUnique( item, element ) 
+		)
+		if ( alreadyIn ) return undefined
+
+		this[ pName ].push( element )
+		this.notify({ [arrayPropName]: this[ arrayPropName as string ] })
+		return element
+	}
+
+	/**
+	 * Removes an element from an arbitrary array property of this class and fires
+	 * a change event on operation success.
+	 * 
+	 * @param arrayPropName the name of the array property of this class where you
+	 * 											want to insert the	new element.
+	 * @param element the element to be inserted
+	 * @param isEqual a function that checks for equity of the two elements 
+	 * 									passed as parameter. If the returned value is true, the 
+	 * 									value will be	removed from the array. 
+	 * @returns the removed element or undefined if the element was not removed.
+	 */
+	protected removeAndNotify<T extends EntropicComponent>( 
+		arrayPropName: ClassArrayPropNames<T>, 
+		element: ArrayPropsElem<T>,
+		isEqual: CompareFunction<T>
+	): ArrayPropsElem<T> | undefined {
+
+		const pName = '_' + String( arrayPropName );
+
+		const originalLength = this[ pName ].length
+
+		this[ pName ] = this[ pName ].filter( 
+			( item: ArrayPropsElem<T> ) => !isEqual( item, element ) 
+		)
+
+		if ( originalLength === this[ pName ].length ) {
+			return undefined
+		}
+
+		this.notify({ [arrayPropName]: this[ arrayPropName as string ] })
+		return element
+	}
+
+	private _onChange: Observable<PropChangeEvent<EntropicComponent>> = new Observable<PropChangeEvent<EntropicComponent>>()
+}