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 =
(mutator: Mutator , mutation: MutationLike ) => void
export type TransformationConsumer =
(transformation: (current: Datar ) => 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 extends BaseAtom implements AtomLike {
private readonly _options: Required
private readonly _consumers: Set >
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 (
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 {
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 )(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 {
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)) {
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'))