import { isNil, isFunction, isObject, isPlainObject, isEmpty, isUndefined } from '../../internal/base' import { syncScheduler, asyncScheduler } from '../../external/scheduler' import { isPausor, isTerminator } from '../metas' import { Mutator, Datar, isDatar, isMutator, DEFAULT_TRANSFORMATION_LIFT_OPTIONS, DEFAULT_MUTATOR_OPTIONS } from '../particles' import { AtomType, BaseAtom, isAtomLike, isDataLike, DEFAULT_BASEATOM_OPTIONS, DEFAULT_SUBSCRIBE_OPTIONS, DEFAULT_ATOM_TRIGGER_REGISTER_OPTIONS } from './base.atom' import type { Vacuo } from '../metas' import type { MutatorOptions, TransformationLiftOptions, MutatorTransformation, LiftBothTransformation, LiftLeftTransformation, LiftRightTransformation, MutatorOriginalTransformationUnion } from '../particles' import type { AtomLike, DataLike, MutationLike, BaseAtomOptions, SubscribeOptions, Subscription, AtomTriggerRegisterOptions, TriggerController, InternalTrigger, Trigger } from './base.atom' import type { DataSubscription } from './data.atom' /****************************************************************************************************** * * Mutation Predicatess * ******************************************************************************************************/ /** * @param target anything * @return { boolean } whether the target is a Mutation instance */ export function isMutation

(target: Mutation): target is Mutation export function isMutation

(target: unknown): target is Mutation export function isMutation

(target: any): target is Mutation { return isObject(target) && target.isMutation } /****************************************************************************************************** * * Mutation Classes * ******************************************************************************************************/ /** * */ export interface MutationOptions

extends BaseAtomOptions { lift?: TransformationLiftOptions mutator?: MutatorOptions isLifted?: boolean originalTransformation?: null | MutatorOriginalTransformationUnion } export const DEFAULT_MUTATION_OPTIONS: Required> = { ...DEFAULT_BASEATOM_OPTIONS, lift: DEFAULT_TRANSFORMATION_LIFT_OPTIONS, mutator: DEFAULT_MUTATOR_OPTIONS, isLifted: false, originalTransformation: null } export type MutatorConsumer

= (mutator: Mutator, mutation: MutationLike) => void export type TransformationConsumer

= (transformation: (current: Datar, ...args: any[]) => C, mutation: MutationLike) => void export type MutationConsumer

= MutatorConsumer | TransformationConsumer export interface MutationSubscription

extends Subscription { proxyConsumer: MutatorConsumer } export type MutationTriggerAccepted

= Mutator | ((...args: any[]) => C) | C export type MutationTrigger

= Trigger> /** * */ export class Mutation

extends BaseAtom implements AtomLike { private readonly _options: Required> private _mutator: Mutator private readonly _consumers: Set> private readonly _subscriptions: Set> private readonly _observations: Map, DataSubscription

> constructor (mutator: Mutator, options: MutationOptions = DEFAULT_MUTATION_OPTIONS) { super() if (!isMutator(mutator)) { throw (new TypeError('"mutator" is expected to be type of "Mutator".')) } if (!isPlainObject(options)) { throw (new TypeError('"options" is expected to be type of "PlainObject".')) } this._options = { ...DEFAULT_MUTATION_OPTIONS, ...options } this._mutator = mutator this._consumers = new Set() this._subscriptions = new Set() this._observations = new Map() } get type (): AtomType { return AtomType.Mutation } get atomType (): AtomType { return AtomType.Mutation } get particleName (): string { return 'mutator' } get particle (): Mutator { return this._mutator } get metaName (): string { return 'transformation' } get meta (): Mutator['transformation'] { return this._mutator.transformation } get options (): Required> { return this._options } /** * Set Mutation's options by key. */ setOptions(key: Key, value: Required[Key]): void { this._options[key] = value } /** * @return { true } true */ get isMutation (): true { return true } get isEmpty (): boolean { return this._mutator.isEmpty } /** * Create a new Mutation instance with Mutator or Function. * * @param transformation can be a Mutator or a function * @param [options.mutator] Mutator options, when use a Function to create, * `Mutator.of` will be used as Mutator factory, * and `options.mutator` will be used as Mutator options. */ static of

( transformation: MutatorTransformation | Mutator, options: MutationOptions = DEFAULT_MUTATION_OPTIONS ): Mutation { const preparedOptions = { ...DEFAULT_MUTATION_OPTIONS, ...options } if (isMutator(transformation)) { return new Mutation(transformation, preparedOptions) } else if (isFunction(transformation)) { return new Mutation(Mutator.of(transformation, undefined, preparedOptions.mutator), preparedOptions) } else { throw (new TypeError('"transformation" is expected to be type of "Mutator" or "Function".')) } } /** * Same as `Mutation.of(Mutator.of(VACUO, CHAOS, options.mutator), options)`. */ static empty

(options: MutationOptions = DEFAULT_MUTATION_OPTIONS): Mutation { const preparedOptions = { ...DEFAULT_MUTATION_OPTIONS, ...options } return new Mutation(Mutator.empty(preparedOptions.mutator), preparedOptions) } static ofLift

( transformation: MutatorOriginalTransformationUnion, options: MutationOptions = DEFAULT_MUTATION_OPTIONS ): Mutation { const preparedOptions = { ...DEFAULT_MUTATION_OPTIONS, ...options } return new Mutation( Mutator.ofLift(transformation, preparedOptions.lift), { ...preparedOptions, isLifted: true, originalTransformation: transformation } ) } static ofLiftBoth

( transformation: LiftBothTransformation, options: MutationOptions = DEFAULT_MUTATION_OPTIONS ): Mutation { const preparedOptions = { ...DEFAULT_MUTATION_OPTIONS, ...options } return new Mutation( Mutator.ofLiftBoth(transformation), { ...preparedOptions, isLifted: true, originalTransformation: transformation } ) } static ofLiftLeft

( transformation: LiftLeftTransformation, options: MutationOptions = DEFAULT_MUTATION_OPTIONS ): Mutation { const preparedOptions = { ...DEFAULT_MUTATION_OPTIONS, ...options } return new Mutation( Mutator.ofLiftLeft(transformation), { ...preparedOptions, isLifted: true, originalTransformation: transformation } ) } static ofLiftRight

( transformation: LiftRightTransformation, options: MutationOptions = DEFAULT_MUTATION_OPTIONS ): Mutation { const preparedOptions = { ...DEFAULT_MUTATION_OPTIONS, ...options } return new Mutation( Mutator.ofLiftRight(transformation), { ...preparedOptions, isLifted: true, originalTransformation: transformation } ) } /** * Mutator of Mutation. */ get mutator (): Mutator { return this._mutator } /** * Transformation of Mutator of Mutation. * * If the transformation is lifted, the original transformation will * be returned as first choice instead of lifted transformation. */ get transformation (): Mutator['transformation'] { return this._mutator.transformation } get originalTransformation (): MutatorOriginalTransformationUnion | null { return this._options.originalTransformation } /** * Stream value of Mutation. * * @param consumer The consumer will be invoked by "trigger" method when there is a adequate value. * @param options * @param [options.isExtracted = false] Whether to extract the value from the datar before it be passed to consumer. */ subscribe (consumer: MutatorConsumer): MutationSubscription subscribe (consumer: MutatorConsumer, options: SubscribeOptions & { isExtracted: false }): MutationSubscription subscribe (consumer: TransformationConsumer, options: SubscribeOptions & { isExtracted: true }): MutationSubscription // NOTE: catch all overload subscribe (consumer: MutationConsumer, options?: SubscribeOptions): MutationSubscription subscribe (consumer: MutationConsumer, options: SubscribeOptions = DEFAULT_SUBSCRIBE_OPTIONS): MutationSubscription { const preparedOptions = { ...DEFAULT_SUBSCRIBE_OPTIONS, ...options } const { isExtracted } = preparedOptions let proxyConsumer: MutatorConsumer if (isExtracted) { /** * Mutation's transformation may not be a curried function, eg. created by Mutation.of(transformation, options). * So the body of `fakeTransformation` can not't be `consumer(mutator.transformation(mutator.datar))`. */ proxyConsumer = (mutator, mutation) => { // Q: consider what is `transformation`, the `transformation` function or // the `transformation` function bind `Mutation.datar` as 1st argument? // A: latter is more correct. const fakeTransformation = (current: Datar, ...args: any[]): C => { return mutator.transformation(mutator.datar, current, ...args) } return (consumer as TransformationConsumer)(fakeTransformation, mutation) } } else { proxyConsumer = consumer as MutatorConsumer } this._consumers.add(proxyConsumer) const subscription = { subscribeOptions: preparedOptions, originalConsumer: consumer, proxyConsumer: proxyConsumer, unsubscribe: () => { const unsubscribed = this._consumers.delete(proxyConsumer) && this._subscriptions.delete(subscription) return unsubscribed } } this._subscriptions.add(subscription) return subscription } /** * Same as `.subscribe(consumer, { ...options, isExtracted: true })`. * * Get a transformation of mutator of mutation, which bind latest * datar of mutation as first argument. */ subscribeTransformation ( consumer: TransformationConsumer, options: SubscribeOptions = DEFAULT_SUBSCRIBE_OPTIONS ): MutationSubscription { return this.subscribe(consumer, { ...DEFAULT_SUBSCRIBE_OPTIONS, ...options, isExtracted: true }) } /** * Given a consumer, find and return the subscription. */ getSubscriptionByConsumer (consumer: MutationConsumer): MutationSubscription | undefined { let subscriptionFound: MutationSubscription | undefined this._subscriptions.forEach(subscription => { if (subscription.originalConsumer === consumer || subscription.proxyConsumer === consumer) { subscriptionFound = subscription } }) return subscriptionFound } /** * Given a hostAtom, find and return the subscription. */ getSubscriptionByHostAtom (hostAtom: AtomLike): MutationSubscription | undefined { let subscriptionFound: MutationSubscription | undefined this._subscriptions.forEach(subscription => { if (subscription.hostAtom === hostAtom) { subscriptionFound = subscription } }) return subscriptionFound } /** * Given a consumer or atom, find and return the subscription. */ getSubscription (consumerOrHostAtom: MutationConsumer | AtomLike): MutationSubscription | undefined { if (isFunction(consumerOrHostAtom)) { return this.getSubscriptionByConsumer(consumerOrHostAtom) } else if (isAtomLike(consumerOrHostAtom)) { return this.getSubscriptionByHostAtom(consumerOrHostAtom) } else { throw (new TypeError('Unexpected type of "consumerOrHostAtom".')) } } /** * Given a consumer or subscription, unsubscribe it. */ unsubscribe (target: MutationConsumer | MutationSubscription | AtomLike): boolean { if (isFunction(target) || isAtomLike(target)) { let unsubscribed = false const subscription = this.getSubscription(target) if (!isUndefined(subscription)) { unsubscribed = subscription.unsubscribe() } return unsubscribed } else if (isFunction(target.unsubscribe)) { const unsubscribed = target.unsubscribe() return unsubscribed } else { throw (new TypeError('Unexpected type of "target".')) } } /** * Unsubscribe all subscriptions. */ unsubscribeAll (): boolean { const unsubscribed: boolean[] = [] this._subscriptions.forEach((subscription) => { unsubscribed.push(subscription.unsubscribe()) }) return unsubscribed.every((unsubscribed) => unsubscribed) } /** * `Empty mutator` will not be triggered. * * @param mutator mutator */ trigger (mutator?: Mutator): void { const _mutator = mutator ?? this._mutator if (!isMutator(_mutator)) { throw (new TypeError('"Mutation" must be triggered with a "Mutator".')) } if (!isEmpty(_mutator)) { const { isAsync } = this._options const batchScheduler = isAsync ? asyncScheduler : syncScheduler batchScheduler(() => { this._consumers.forEach(consumer => { if (isAsync) { asyncScheduler(() => consumer(_mutator, this)) } else { // syncScheduler(() => consumer(_mutator, this)) consumer(_mutator, this) } }) }) } } /** * Internally call `trigger` method which will not trigger `empty mutator`, * so the `Vacuo` value will not be triggered by `triggerTransformation` method. * * @param transformation transformation */ triggerTransformation (transformation?: Mutator['transformation']): void { if (isNil(transformation)) { return this.trigger() } else { return this.trigger(Mutator.of(transformation)) } } /** * Change the value of Mutation in a stream manner. * * Given "data" will be **upstream** of current Mutation, which is different from "beObservedBy" method. * * @param mutation data -> current mutation (-> other data) */ observe (data: DataLike

): DataSubscription

{ if (!isDataLike(data)) { throw (new TypeError('"Mutation" can only observe a "Data".')) } const subscription = data.subscribe((_datar: (typeof data)['datar'], _data: typeof data) => { this.mutate(_datar, _data) }, { hostAtom: this }) this._observations.set(data, subscription) return subscription } unobserve (data: DataLike

): boolean { const observation = this._observations.get(data) let unobserved = false if (!isUndefined(observation)) { unobserved = observation.unsubscribe() } return unobserved } unobserveAll (): boolean { const unobserved: boolean[] = [] this._observations.forEach((observation) => { unobserved.push(observation.unsubscribe()) }) return unobserved.every((unobserved) => unobserved) } /** * Change the value of Mutation in a stream manner. * * Given "data" will be **downstream** of current Mutation, which is different from "observe" method. * * @param mutation (other data ->) current mutation -> data */ beObservedBy (data: DataLike): MutationSubscription { const subscription = data.observe(this) return subscription // return this.subscribe((mutator, mutation) => { // data.mutate(mutator, mutation) // }) } /** * Change the value of Mutation in a static manner. * * take datar-like param(convert to datar) * -> run datar with current mutator & contexts * -> wrap and save result of datar.run as new mutator * -> trigger consumers with new mutator & contexts * * @param datar Will be the 2nd param of mutator's operation. * @param data * @return { Mutation } Mutation(this) */ mutate (datar: DataLike

| Datar

| P, data?: DataLike

): this { let _datar: Datar

if (isDatar

(datar)) { _datar = datar } else if (isDataLike

(datar)) { _datar = datar.datar } else { _datar = Datar.of(datar) } let _data: DataLike

| undefined if (isNil(data)) { _data = isDataLike(datar) ? datar : _data } else { if (isDataLike(data)) { _data = data } else { throw (new TypeError('"data" is expected to be type of "Data".')) } } // Datar's run method will always return the transformation of mutator which passed to it as first argument. const newMutator = Mutator.of(_datar.run(this._mutator, _data), _datar, this._mutator.options) if (isTerminator(_datar.value)) { // If the value of received datar is TERMINATOR, // throw away the result, // do not update the mutator of current Mutation, // and do not trigger consumers(subscribers). } else if (isPausor(_datar.value)) { // If the value of received datar is PAUSOR, // update the mutator of current Mutation with new Mutator, // but do not trigger consumers(subscribers). this._mutator = newMutator } else { // Else, // update the mutator of current Mutation with new Mutator, // and trigger consumers(subscribers). this._mutator = newMutator this.trigger() } return this } /** * @param trigger Which Take an internalTrigger(Function) as first parameter, * invoke internalTrigger with any value will lead to * Mutation's trigger method be triggerd with that value. * @param options * @param [options.forceWrap = false] If true, the emitted value of trigger will always be wrapped in Mutator. * @return { TriggerController } TriggerController */ registerTrigger ( trigger: MutationTrigger, options: AtomTriggerRegisterOptions = DEFAULT_ATOM_TRIGGER_REGISTER_OPTIONS ): TriggerController { if (isNil(trigger)) { throw (new TypeError('"trigger" is required.')) } if (!isFunction(trigger)) { throw (new TypeError('"trigger" is expected to be type of "Function".')) } if (!isPlainObject(options)) { throw (new TypeError('"options" is expected to be type of "PlainObject".')) } const { forceWrap } = { ...DEFAULT_ATOM_TRIGGER_REGISTER_OPTIONS, ...options } const internalTrigger: InternalTrigger> = (acceptValue, ...args) => { if (forceWrap) { return this.trigger(...[Mutator.of(() => acceptValue), ...args]) } if (!isMutator(acceptValue)) { if (!isFunction(acceptValue)) { return this.trigger(...[Mutator.of(() => acceptValue), ...args]) } else { return this.trigger(...[Mutator.of(acceptValue), ...args]) } } else { return this.trigger(...[acceptValue, ...args]) } } const controller = trigger(internalTrigger) return controller } } /** * GC, aka. Garbage Clean, used by mediator to release memories. */ export const GC_MUTATION = Mutation.of(() => Symbol('GC_MUTATION'))