import { isObject, isString, isPlainObject, isFunction } from '../internal/base' import { Vain } from './vain' import { VACUO, isVacuo } from './metas' import type { Vacuo } from './metas' import type { DataLike, MutationLike } from './atoms' /****************************************************************************************************** * Particles * * Chaos -> Chaos of Datar & Mutator. * * Datar -> Designed to carry the value of Data. * * Mutator -> Designed to carry the transformation of Mutation. ******************************************************************************************************/ /** * Number of particles is finite. Using a `enum` to group them is reasonable. */ export enum ParticleType { Chaos = '[particle Chaos]', Datar = '[particle Datar]', Mutator = '[particle Mutator]' } /****************************************************************************************************** * * Particle Predicates * ******************************************************************************************************/ /** * @param target anything * @return { boolean } whether the target is a Particle instance */ export const isParticle = (target: any): target is Particle => isObject(target) && target.isParticle /** * @param target anything * @return { boolean } whether the target is a Chaos instance */ export const isChaos = (target: any): target is Chaos => isObject(target) && target.isChaos /** * @param target anything * @return { boolean } whether target is a Datar instance */ export function isDatar (target: Datar): target is Datar export function isDatar (target: unknown): target is Datar export function isDatar (target: any): target is Datar { return isObject(target) && target.isDatar } /** * @param target anything * @return { boolean } whether target is a Mutator instance */ export function isMutator

(target: Mutator): target is Mutator export function isMutator

(target: unknown): target is Mutator export function isMutator

(target: any): target is Mutator { return isObject(target) && target.isMutator } /****************************************************************************************************** * * Particle Classes * ******************************************************************************************************/ /** * */ export interface BaseParticleOptions { /** * HP, aka. High Performance */ isHPMode?: boolean } export const DEFAULT_BASE_PARTICLE_OPTIONS: Required = { isHPMode: true } /** * Base particle class. */ export abstract class Particle extends Vain { isParticle: true constructor () { super() this.isParticle = true if (new.target === Particle) { throw new Error('Particle class can not be instantiated!') } } abstract get particleType (): ParticleType } /** *—————————————————————————————————————————————— Chaos Meta ———————————————————————————————————————————————————— */ /** * */ export class Chaos extends Particle { isChaos: true value: Vacuo transformation: Vacuo constructor () { super() this.isChaos = true this.value = VACUO this.transformation = VACUO } get type (): ParticleType { return ParticleType.Chaos } get particleType (): ParticleType { return ParticleType.Chaos } } /** * Global Chaos instance. * @see {@link Chaos} */ export const CHAOS = new Chaos() /** *—————————————————————————————————————————————— Datar Meta ———————————————————————————————————————————————————— */ /** * */ export interface DatarOptions extends BaseParticleOptions {} export const DEFAULT_DATAR_OPTIONS: Required = { ...DEFAULT_BASE_PARTICLE_OPTIONS } /** * mutator of datar's output type should be same as datar's value type. */ type MutatorOfDatar = Mutator type ValidMutatorOfDatar = | Mutator | Chaos /** * @return { boolean } whether the target is a valid mutator of datar */ export function isValidMutatorOfDatar (target: ValidMutatorOfDatar): target is ValidMutatorOfDatar export function isValidMutatorOfDatar (target: unknown): target is ValidMutatorOfDatar export function isValidMutatorOfDatar (target: any): target is ValidMutatorOfDatar { return isChaos(target) || isMutator(target) } /** * Designed to carry the value of Data. * * @param [options.isHPMode = true] whether the datar is in HPMode, when in HPMode, * the mutator of datar will always be Chaos. */ export class Datar extends Particle { value: V options: Required mutator: ValidMutatorOfDatar constructor ( value: V, mutator: ValidMutatorOfDatar = CHAOS, options: DatarOptions = DEFAULT_DATAR_OPTIONS ) { super() if (!isValidMutatorOfDatar(mutator)) { throw (new TypeError('"mutator" is expected to be type of "Mutator" | "Chaos".')) } if (!isPlainObject(options)) { throw (new TypeError('"options" is expected to be type of "PlainObject".')) } this.options = { ...DEFAULT_DATAR_OPTIONS, ...options } const { isHPMode } = this.options this.value = value // If the datar is in HPMode, the mutator will always be Chaos. // So it won't occpy much memory. if (!isHPMode) { this.mutator = mutator } else { this.mutator = CHAOS } } get type (): ParticleType { return ParticleType.Datar } get particleType (): ParticleType { return ParticleType.Datar } /** * Same as `new Datar()`. */ static of ( value: V, mutator: ValidMutatorOfDatar = CHAOS, options: DatarOptions = DEFAULT_DATAR_OPTIONS ): Datar { return new Datar(value, mutator, options) } /** * When we create a new datar instance with `Datar.empty`, its value will be `VACUO` for sure. * But the reason we create a empty datar is to contain some type of value in the future. * The `const someDatar = Datar.empty() as Datar` seems inevitable. * It is advisable to always set a initial value for any type of value. */ static empty (options: DatarOptions = DEFAULT_DATAR_OPTIONS): Datar { return new Datar(VACUO, CHAOS, options) } get isDatar (): true { return true } get isEmpty (): boolean { return isVacuo(this.value) } /** * @param mutator * @return { Datar } this */ fill (mutator: MutatorOfDatar): this { if (!isMutator(mutator)) { throw (new TypeError('"mutator" is expected to be type of "Mutator".')) } this.mutator = mutator return this } /** * Rarely used, this method exists to ensure the symmetry of Datar and Mutator. * * @param mutator the mutator to be applied * @param args exists for the symmetry of Mutator.run * @return transformation function of specified mutator */ run >(mutator: M, data?: DataLike, ...args: any[]): M['transformation'] { if (!isMutator(mutator)) { throw (new TypeError('"mutator" is expected to be type of "Mutator".')) } return mutator.transformation } } /** *—————————————————————————————————————————————— Mutator Meta ———————————————————————————————————————————————————— */ /** * */ export type TransformationLiftPositions = 'unknown' | 'both' | 'left' | 'right' | 'none' export interface TransformationLiftOptions { position?: TransformationLiftPositions } export const DEFAULT_TRANSFORMATION_LIFT_OPTIONS: Required = { position: 'both' } export interface MutatorOptions extends BaseParticleOptions { lift?: TransformationLiftOptions } export const DEFAULT_MUTATOR_OPTIONS: Required = { ...DEFAULT_BASE_PARTICLE_OPTIONS, lift: DEFAULT_TRANSFORMATION_LIFT_OPTIONS } const _isValidMutatorOptions = (tar: any): tar is MutatorOptions => { return isPlainObject(tar) && isPlainObject(tar.lift) && tar.lift.position !== undefined } export type MutatorTransformation

= (previous: Chaos | Datar

, current: Datar, mutation?: MutationLike, ...contexts: Contexts) => C type DatarOfMutator

= Datar

type ValidDatarOfMutator

= Datar

| Chaos /** * Predicate whether the target is a valid datar of mutator, i.e. Chaos or Datar. */ export function isValidDatarOfMutator

(target: ValidDatarOfMutator): target is ValidDatarOfMutator export function isValidDatarOfMutator

(target: unknown): target is ValidDatarOfMutator export function isValidDatarOfMutator

(target: any): target is ValidDatarOfMutator { return isChaos(target) || isDatar(target) } export type LiftBothTransformation

= (previous: Vacuo | P, current: C, mutation?: MutationLike, ...contexts: Contexts) => C export type LiftLeftTransformation

= (previous: Vacuo | P, current: Datar, mutation?: MutationLike, ...contexts: Contexts) => C export type LiftRightTransformation

= (previous: Chaos | Datar

, current: C, mutation?: MutationLike, ...contexts: Contexts) => C export type MutatorOriginalTransformationUnion

= | MutatorTransformation | LiftBothTransformation | LiftLeftTransformation | LiftRightTransformation /** * Designed to carry the transformation of Mutation. */ export class Mutator

extends Particle { transformation: MutatorTransformation options: Required datar: ValidDatarOfMutator constructor ( transformation: MutatorTransformation, datar: ValidDatarOfMutator

= CHAOS, options: MutatorOptions = DEFAULT_MUTATOR_OPTIONS ) { super() if (!isFunction(transformation)) { throw (new TypeError('"transformation" is expected to be type of "Function".')) } if (!isValidDatarOfMutator(datar)) { throw (new TypeError('"datar" is expected to be type of "Datar".')) } if (!isPlainObject(options)) { throw (new TypeError('"options" is expected to be type of "PlainObject".')) } // When make Mutator using bare `Mutator.of` or bare `new Mutator()` without specify `lift`, // mark its position as `'unknown'` by default. if (options.lift === undefined) { options.lift = { position: 'unknown' as const } } this.options = { ...DEFAULT_MUTATOR_OPTIONS, ...options } const { isHPMode } = options this.transformation = transformation // NOTE: Mutator's execute is lazy, so it's HPMode is not like Datar's. // It's not necessary to make an extremely strict HPMode. this.datar = datar } get type (): ParticleType { return ParticleType.Mutator } get particleType (): ParticleType { return ParticleType.Mutator } static of

( transformation: MutatorTransformation, datar: ValidDatarOfMutator

= CHAOS, options: MutatorOptions = DEFAULT_MUTATOR_OPTIONS ): Mutator { return new Mutator(transformation, datar, options) } static ofLift

( transformation: MutatorOriginalTransformationUnion, options: MutatorOptions | TransformationLiftOptions = DEFAULT_MUTATOR_OPTIONS ): Mutator { const preparedOptions = _isValidMutatorOptions(options) ? { ...DEFAULT_MUTATOR_OPTIONS, ...options } : { ...DEFAULT_MUTATOR_OPTIONS, lift: options } return this.of(this.lift(transformation, preparedOptions.lift), undefined, preparedOptions) } static ofLiftBoth ( transformation: LiftBothTransformation, options: MutatorOptions = DEFAULT_MUTATOR_OPTIONS ): Mutator { const preparedOptions = { ...DEFAULT_MUTATOR_OPTIONS, ...options, lift: { ...(options.lift ?? {}), position: 'both' as const } } return this.of(this.liftBoth(transformation), undefined, preparedOptions) } static ofLiftLeft ( transformation: LiftLeftTransformation, options: MutatorOptions = DEFAULT_MUTATOR_OPTIONS ): Mutator { const preparedOptions = { ...DEFAULT_MUTATOR_OPTIONS, ...options, lift: { ...(options.lift ?? {}), position: 'left' as const } } return this.of(this.liftLeft(transformation), undefined, preparedOptions) } static ofLiftRight ( transformation: LiftRightTransformation, options: MutatorOptions = DEFAULT_MUTATOR_OPTIONS ): Mutator { const preparedOptions = { ...DEFAULT_MUTATOR_OPTIONS, ...options, lift: { ...(options.lift ?? {}), position: 'right' as const } } return this.of(this.liftRight(transformation), undefined, preparedOptions) } static empty (options: MutatorOptions = {}): Mutator { // `options` will be complemented in `new Mutator()` return new Mutator(VACUO, CHAOS, options) } get isMutator (): true { return true } get isEmpty (): boolean { return isVacuo(this.transformation) } /** * Dispatch transformation to correct lift method according to the given options. * * @param transformation * @param [options = DEFAULT_TRANSFORMATION_LIFT_OPTIONS] default to `{ position: 'both' }` */ static lift

( transformation: MutatorOriginalTransformationUnion, options: TransformationLiftOptions = DEFAULT_TRANSFORMATION_LIFT_OPTIONS ): MutatorTransformation { // transformation will be checked in the specific lift method later if (!isPlainObject(options)) { throw (new TypeError('"options" is expected to be type of "PlainObject".')) } const { position } = { ...DEFAULT_TRANSFORMATION_LIFT_OPTIONS, ...options } if (!isString(position)) { throw (new TypeError('"type" is expected to be type of "String".')) } if (options.position === 'none' || options.position === 'unknown') { return transformation as MutatorTransformation } else if (options.position === 'both') { return this.liftBoth(transformation as LiftBothTransformation) } else if (options.position === 'left') { return this.liftLeft(transformation as LiftLeftTransformation) } else if (options.position === 'right') { return this.liftRight(transformation as LiftRightTransformation) } else { throw (new TypeError('"type" is expected be one of "none" | "both" | "left" | "right" | "unknown".')) } } /** * Automatically unwrap both previous datar & current datar to value. * * @param transformation * @return { AnyFunction } wrapped transformation function */ static liftBoth

(transformation: LiftBothTransformation): MutatorTransformation { if (!isFunction(transformation)) { throw (new TypeError('"transformation" is expected to be type of "Function".')) } return (prevDatar, datar, ...args) => { return transformation(prevDatar.value, datar.value, ...args) } } /** * Automatically unwrap previous datar to value, keep current datar. * * @param transformation * @return { function } wrapped transformation function */ static liftLeft

(transformation: LiftLeftTransformation): MutatorTransformation { if (!isFunction(transformation)) { throw (new TypeError('"transformation" is expected to be type of "Function".')) } return (prevDatar, datar, ...args) => { return transformation(prevDatar.value, datar, ...args) } } /** * Automatically unwrap current datar to value, keep previous datar. * * @param transformation * @return { function } wrapped transformation function */ static liftRight

(transformation: LiftRightTransformation): MutatorTransformation { if (!isFunction(transformation)) { throw (new TypeError('"transformation" is expected to be type of "Function".')) } return (prevDatar, datar, ...args) => { return transformation(prevDatar, datar.value, ...args) } } /** * @param datar * @return { Mutator } this */ fill (datar: DatarOfMutator): this { if (!isDatar(datar)) { throw (new TypeError('"datar" is expected to be type of "Datar".')) } this.datar = datar return this } /** * Given Atom Flow: Data A -> Mutation -> Data B * * -> Data A is observed by Mutation, Mutation is observed by Data B; * * -> Data A emits a datar, Mutation takes that datar as the 1st parameter of its inner transformation; * * -> Mutation takes datar from Data A, then emits a mutator, Data B will take that mutator; * * -> Data B takes mutator from Mutation, then pass its own datar to that mutator's transformation as the 2nd parameter; * * -> The transformation evaluates while it has both two parameters, the result will be wrapped in a new datar; * * -> The new datar of transformation's evaluate result will be the new datar of Data B. * * @param datar the datar to be passed to the transformation as 2nd parameter * @param args the rest of the arguments (3rd and after) to be passed to the transformation * @return Return type of transformation */ run (datar: Datar, mutation?: MutationLike, ...args: any[]): C { if (!isDatar(datar)) { throw (new TypeError('"datar" is expected to be type of "Datar".')) } return this.transformation(this.datar, datar, mutation, ...args) } }