@thomas-siegfried/tapout 0.0.1

package/src/core.ts

@@ -0,0 +1,60 @@
+export { options } from './options.js';
+
+export const version = '1.0.0';
+
+export { Subscribable, Subscription, isSubscribable, isReadableSubscribable, valuesArePrimitiveAndEqual } from './subscribable.js';
+export type { SubscriptionCallback, ReadableSubscribable } from './subscribable.js';
+
+export {
+  begin,
+  end,
+  registerDependency,
+  ignore,
+  getDependenciesCount,
+  getDependencies,
+  isInitial,
+  getCurrentComputed,
+} from './dependencyDetection.js';
+export type { TrackingFrame } from './dependencyDetection.js';
+
+export { Observable, isObservable } from './observable.js';
+
+export { ObservableArray, isObservableArray, DESTROY, isDestroyed } from './observableArray.js';
+
+export { compareArrays, findMovesInArrayComparison } from './compareArrays.js';
+export type { ArrayChange, CompareArraysOptions } from './compareArrays.js';
+
+export { Computed, PureComputed, isComputed, isPureComputed } from './computed.js';
+export type { ComputedOptions } from './computed.js';
+
+export { registerExtender, throttle, debounce } from './extenders.js';
+export type { ExtenderHandler, ExtenderMap, ExtenderOptions, RateLimitOptions } from './extenders.js';
+
+export { effect, observe } from './effects.js';
+export type { EffectHandle } from './effects.js';
+
+export { Event, EventSubscribable, EventSubscription, AggregateEvent, isEvent, isEventSubscribable, isAggregateEvent } from './event.js';
+export type { EventCallback, Constructor } from './event.js';
+
+export { DisposableGroup } from './disposable.js';
+export type { Disposable } from './disposable.js';
+
+export { reactive, reactiveArray, computed, getObservable, replaceObservable } from './decorators.js';
+
+export {
+  unwrapObservable, peekObservable, toJS, toJSON, when,
+  catchFunctionErrors,
+} from './utils.js';
+
+export { schedule, cancel, runEarly, resetForTesting } from './tasks.js';
+import * as tasks from './tasks.js';
+export { tasks };
+
+import { Observable } from './observable.js';
+import { Computed } from './computed.js';
+
+export function isWritableObservable(value: unknown): value is Observable<unknown> | Computed<unknown> {
+  if (value instanceof Observable) return true;
+  if (value instanceof Computed) return value.hasWriteFunction;
+  return false;
+}

package/src/decorators.ts

@@ -0,0 +1,407 @@
+import { Observable } from './observable.js';
+import { ObservableArray } from './observableArray.js';
+import { Computed } from './computed.js';
+import type { Subscribable } from './subscribable.js';
+import type { ExtenderOptions } from './extenders.js';
+import { registerDependency } from './dependencyDetection.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnySubscribable = Subscribable<any>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyAccessorValue = ClassAccessorDecoratorTarget<any, any>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyAccessorContext = ClassAccessorDecoratorContext<any, any>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyAccessorResult = ClassAccessorDecoratorResult<any, any>;
+
+// --- Observable registry for getObservable() ---
+
+const accessorRegistry = new Map<string | symbol, WeakMap<object, AnySubscribable>>();
+const computedStorage = new WeakMap<object, Map<string | symbol, Computed<unknown>>>();
+
+function storeObservable(instance: object, key: string | symbol, obs: AnySubscribable): void {
+  let instanceMap = accessorRegistry.get(key);
+  if (!instanceMap) {
+    instanceMap = new WeakMap();
+    accessorRegistry.set(key, instanceMap);
+  }
+  instanceMap.set(instance, obs);
+}
+
+function lookupObservable(instance: object, key: string | symbol): AnySubscribable | undefined {
+  const instanceMap = accessorRegistry.get(key);
+  if (instanceMap) {
+    return instanceMap.get(instance);
+  }
+  const compMap = computedStorage.get(instance);
+  if (compMap) {
+    return compMap.get(key);
+  }
+  return undefined;
+}
+
+// --- Detection helper ---
+
+function isStage3Context(arg: unknown): arg is { kind: string; name: string | symbol } {
+  return typeof arg === 'object' && arg !== null && 'kind' in arg;
+}
+
+// --- @reactive: Stage 3 accessor path ---
+
+function createStage3Reactive(extenders?: ExtenderOptions) {
+  return (_value: AnyAccessorValue, context: AnyAccessorContext): AnyAccessorResult => ({
+    init(initialValue: unknown): unknown {
+      const obs = new Observable(initialValue);
+      if (extenders) obs.extend(extenders);
+      storeObservable(this as object, context.name, obs);
+      return obs;
+    },
+    get(this: object): unknown {
+      const obs = lookupObservable(this, context.name) as Observable<unknown>;
+      return obs.get();
+    },
+    set(this: object, newValue: unknown): void {
+      const obs = lookupObservable(this, context.name) as Observable<unknown>;
+      obs.set(newValue);
+    },
+  });
+}
+
+// --- @reactive: Legacy property decorator path ---
+
+interface LegacyFieldDescriptor {
+  configurable?: boolean;
+  enumerable?: boolean;
+  writable?: boolean;
+  initializer?: (this: object) => unknown;
+}
+
+function applyLegacyReactive(
+  target: object,
+  propertyKey: string | symbol,
+  descriptor?: LegacyFieldDescriptor,
+  extenders?: ExtenderOptions,
+): PropertyDescriptor {
+  const initializer = descriptor?.initializer;
+  const newDesc: PropertyDescriptor = {
+    configurable: true,
+    enumerable: true,
+    get(this: object) {
+      let obs = lookupObservable(this, propertyKey);
+      if (!obs) {
+        const initValue = initializer ? initializer.call(this) : undefined;
+        obs = new Observable<unknown>(initValue);
+        if (extenders) obs.extend(extenders);
+        storeObservable(this, propertyKey, obs);
+      }
+      return (obs as Observable<unknown>).get();
+    },
+    set(this: object, value: unknown) {
+      let obs = lookupObservable(this, propertyKey);
+      if (!obs) {
+        obs = new Observable<unknown>(value);
+        if (extenders) obs.extend(extenders);
+        storeObservable(this, propertyKey, obs);
+      } else {
+        (obs as Observable<unknown>).set(value);
+      }
+    },
+  };
+  if (!descriptor || typeof descriptor.initializer === 'undefined') {
+    Object.defineProperty(target, propertyKey, newDesc);
+  }
+  return newDesc;
+}
+
+// --- @reactive: Unified decorator ---
+
+/**
+ * A decorator function returned by reactive(options) / reactiveArray(options).
+ * Works as either a Stage 3 accessor decorator or a legacy property decorator.
+ */
+export interface ReactivePropertyDecorator {
+  <This, Value>(value: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): ClassAccessorDecoratorResult<This, Value>;
+  (target: object, propertyKey: string | symbol): void;
+}
+
+export function reactive<This, Value>(value: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): ClassAccessorDecoratorResult<This, Value>;
+export function reactive(target: object, propertyKey: string | symbol): void;
+export function reactive(target: object, propertyKey: string | symbol, descriptor: LegacyFieldDescriptor): PropertyDescriptor;
+export function reactive(options: ExtenderOptions): ReactivePropertyDecorator;
+export function reactive(
+  valueOrOptions: unknown,
+  contextOrKey?: unknown,
+  descriptor?: LegacyFieldDescriptor,
+): unknown {
+  if (contextOrKey === undefined) {
+    const ext = valueOrOptions as ExtenderOptions;
+    return function (target: unknown, contextOrKey2: unknown, descriptor2?: LegacyFieldDescriptor) {
+      if (isStage3Context(contextOrKey2)) {
+        return createStage3Reactive(ext)(target as AnyAccessorValue, contextOrKey2 as AnyAccessorContext);
+      }
+      return applyLegacyReactive(target as object, contextOrKey2 as string | symbol, descriptor2, ext);
+    };
+  }
+  if (isStage3Context(contextOrKey)) {
+    return createStage3Reactive()(valueOrOptions as AnyAccessorValue, contextOrKey as AnyAccessorContext);
+  }
+  return applyLegacyReactive(valueOrOptions as object, contextOrKey as string | symbol, descriptor);
+}
+
+// --- @reactiveArray: Stage 3 accessor path ---
+
+function createStage3ReactiveArray(extenders?: ExtenderOptions) {
+  return (_value: AnyAccessorValue, context: AnyAccessorContext): AnyAccessorResult => ({
+    init(initialValue: unknown): unknown {
+      const arr = Array.isArray(initialValue) ? initialValue : [];
+      const obs = new ObservableArray(arr);
+      if (extenders) obs.extend(extenders);
+      storeObservable(this as object, context.name, obs);
+      return obs;
+    },
+    get(this: object): unknown {
+      const obs = lookupObservable(this, context.name) as ObservableArray<unknown>;
+      registerDependency(obs);
+      return obs;
+    },
+    set(this: object, newValue: unknown): void {
+      const obs = lookupObservable(this, context.name) as ObservableArray<unknown>;
+      obs.set(newValue as unknown[]);
+    },
+  });
+}
+
+// --- @reactiveArray: Legacy property decorator path ---
+
+function applyLegacyReactiveArray(
+  target: object,
+  propertyKey: string | symbol,
+  descriptor?: LegacyFieldDescriptor,
+  extenders?: ExtenderOptions,
+): PropertyDescriptor {
+  const initializer = descriptor?.initializer;
+  const newDesc: PropertyDescriptor = {
+    configurable: true,
+    enumerable: true,
+    get(this: object) {
+      let obs = lookupObservable(this, propertyKey);
+      if (!obs) {
+        const initValue = initializer ? initializer.call(this) : undefined;
+        const arr = Array.isArray(initValue) ? initValue : [];
+        obs = new ObservableArray<unknown>(arr);
+        if (extenders) obs.extend(extenders);
+        storeObservable(this, propertyKey, obs);
+      }
+      registerDependency(obs);
+      return obs;
+    },
+    set(this: object, value: unknown) {
+      let obs = lookupObservable(this, propertyKey);
+      if (!obs) {
+        const arr = Array.isArray(value) ? value : [];
+        obs = new ObservableArray<unknown>(arr);
+        if (extenders) obs.extend(extenders);
+        storeObservable(this, propertyKey, obs);
+      } else {
+        (obs as ObservableArray<unknown>).set(value as unknown[]);
+      }
+    },
+  };
+  if (!descriptor || typeof descriptor.initializer === 'undefined') {
+    Object.defineProperty(target, propertyKey, newDesc);
+  }
+  return newDesc;
+}
+
+// --- @reactiveArray: Unified decorator ---
+
+export function reactiveArray<This, Value>(value: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): ClassAccessorDecoratorResult<This, Value>;
+export function reactiveArray(target: object, propertyKey: string | symbol): void;
+export function reactiveArray(target: object, propertyKey: string | symbol, descriptor: LegacyFieldDescriptor): PropertyDescriptor;
+export function reactiveArray(options: ExtenderOptions): ReactivePropertyDecorator;
+export function reactiveArray(
+  valueOrOptions: unknown,
+  contextOrKey?: unknown,
+  descriptor?: LegacyFieldDescriptor,
+): unknown {
+  if (contextOrKey === undefined) {
+    const ext = valueOrOptions as ExtenderOptions;
+    return function (target: unknown, contextOrKey2: unknown, descriptor2?: LegacyFieldDescriptor) {
+      if (isStage3Context(contextOrKey2)) {
+        return createStage3ReactiveArray(ext)(target as AnyAccessorValue, contextOrKey2 as AnyAccessorContext);
+      }
+      return applyLegacyReactiveArray(target as object, contextOrKey2 as string | symbol, descriptor2, ext);
+    };
+  }
+  if (isStage3Context(contextOrKey)) {
+    return createStage3ReactiveArray()(valueOrOptions as AnyAccessorValue, contextOrKey as AnyAccessorContext);
+  }
+  return applyLegacyReactiveArray(valueOrOptions as object, contextOrKey as string | symbol, descriptor);
+}
+
+// --- @computed ---
+
+function getOrCreateComputed<T>(
+  instance: object,
+  key: string | symbol,
+  readFn: () => T,
+  writeFn?: (value: T) => void,
+): Computed<T> {
+  let map = computedStorage.get(instance);
+  if (!map) {
+    map = new Map();
+    computedStorage.set(instance, map);
+  }
+  let comp = map.get(key) as Computed<T> | undefined;
+  if (!comp) {
+    comp = new Computed<T>({
+      read: readFn,
+      write: writeFn,
+      deferEvaluation: true,
+    });
+    map.set(key, comp as Computed<unknown>);
+  }
+  return comp;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFunction = (...args: any[]) => any;
+
+// Stage 3 @computed implementation
+function applyStage3Computed(
+  value: AnyFunction,
+  context: { kind: string; name: string | symbol },
+): AnyFunction | void {
+  const { kind, name } = context;
+
+  if (kind === 'getter') {
+    const originalGetter = value;
+    return function (this: object) {
+      const comp = getOrCreateComputed(this, name, originalGetter.bind(this));
+      return comp.get();
+    };
+  }
+
+  if (kind === 'setter') {
+    const originalSetter = value;
+    return function (this: object, newValue: unknown): void {
+      const map = computedStorage.get(this);
+      const comp = map?.get(name) as Computed<unknown> | undefined;
+      if (comp) {
+        comp.set(newValue);
+      } else {
+        originalSetter.call(this, newValue);
+      }
+    };
+  }
+
+  if (kind === 'method') {
+    const originalMethod = value;
+    return function (this: object): unknown {
+      const comp = getOrCreateComputed(this, name, originalMethod.bind(this));
+      return comp.get();
+    };
+  }
+}
+
+// Legacy @computed implementation (method / getter+setter decorator)
+function applyLegacyComputed(
+  _target: object,
+  propertyKey: string | symbol,
+  descriptor: PropertyDescriptor,
+): PropertyDescriptor {
+  if (descriptor.get) {
+    const originalGetter = descriptor.get;
+    const originalSetter = descriptor.set;
+
+    descriptor.get = function (this: object) {
+      const comp = getOrCreateComputed(
+        this, propertyKey,
+        originalGetter.bind(this),
+        originalSetter ? originalSetter.bind(this) : undefined,
+      );
+      return comp.get();
+    };
+
+    if (originalSetter) {
+      descriptor.set = function (this: object, value: unknown): void {
+        const map = computedStorage.get(this);
+        const comp = map?.get(propertyKey) as Computed<unknown> | undefined;
+        if (comp) {
+          comp.set(value);
+        } else {
+          originalSetter.call(this, value);
+        }
+      };
+    }
+
+    return descriptor;
+  }
+
+  if (typeof descriptor.value === 'function') {
+    const originalMethod = descriptor.value as AnyFunction;
+    descriptor.value = function (this: object): unknown {
+      const comp = getOrCreateComputed(this, propertyKey, originalMethod.bind(this));
+      return comp.get();
+    };
+    return descriptor;
+  }
+
+  return descriptor;
+}
+
+// --- @computed: Unified decorator ---
+
+/**
+ * A decorator function returned by or used as @computed.
+ * Works as either a Stage 3 getter/setter/method decorator or a legacy method decorator.
+ */
+export interface ComputedMethodDecorator {
+  <This, Value>(value: AnyFunction, context: ClassGetterDecoratorContext<This, Value> | ClassMethodDecoratorContext<This, AnyFunction> | ClassSetterDecoratorContext<This, Value>): AnyFunction | void;
+  (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+}
+
+// Stage 3 overloads
+export function computed<This, Value>(
+  value: AnyFunction,
+  context: ClassGetterDecoratorContext<This, Value> | ClassMethodDecoratorContext<This, AnyFunction> | ClassSetterDecoratorContext<This, Value>,
+): AnyFunction | void;
+// Legacy overload
+export function computed(
+  target: object,
+  propertyKey: string | symbol,
+  descriptor: PropertyDescriptor,
+): PropertyDescriptor | void;
+// Implementation
+export function computed(
+  valueOrTarget: unknown,
+  contextOrKey?: unknown,
+  descriptor?: PropertyDescriptor,
+): unknown {
+  if (isStage3Context(contextOrKey)) {
+    return applyStage3Computed(
+      valueOrTarget as AnyFunction,
+      contextOrKey as { kind: string; name: string | symbol },
+    );
+  }
+  return applyLegacyComputed(
+    valueOrTarget as object,
+    contextOrKey as string | symbol,
+    descriptor!,
+  );
+}
+
+// --- getObservable() / replaceObservable() ---
+
+export function getObservable(target: object, key: string | symbol): AnySubscribable | undefined {
+  let obs = lookupObservable(target, key);
+  if (!obs) {
+    void (target as Record<string | symbol, unknown>)[key];
+    obs = lookupObservable(target, key);
+  }
+  return obs;
+}
+
+export function replaceObservable(instance: object, key: string | symbol, obs: AnySubscribable): void {
+  storeObservable(instance, key, obs);
+}

package/src/dependencyDetection.ts

@@ -0,0 +1,76 @@
+import { type Subscribable, isSubscribable } from './subscribable.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- variance: detection is type-agnostic
+type AnySubscribable = Subscribable<any>;
+
+export interface TrackingFrame {
+  callback: (subscribable: AnySubscribable, id: number) => void;
+  computed?: {
+    getDependenciesCount(): number;
+    getDependencies(): AnySubscribable[];
+  };
+  isInitial?: boolean;
+}
+
+let lastId = 0;
+const outerFrames: Array<TrackingFrame | undefined> = [];
+let currentFrame: TrackingFrame | undefined;
+
+export function getId(): number {
+  return ++lastId;
+}
+
+export function begin(frame?: TrackingFrame): void {
+  outerFrames.push(currentFrame);
+  currentFrame = frame;
+}
+
+export function end(): void {
+  currentFrame = outerFrames.pop();
+}
+
+export function registerDependency(subscribable: AnySubscribable): void {
+  if (currentFrame) {
+    if (!isSubscribable(subscribable)) {
+      throw new Error('Only subscribable things can act as dependencies');
+    }
+    currentFrame.callback(
+      subscribable,
+      subscribable._id || (subscribable._id = getId()),
+    );
+  }
+}
+
+export function ignore<R>(callback: () => R): R {
+  try {
+    begin();
+    return callback();
+  } finally {
+    end();
+  }
+}
+
+export function getDependenciesCount(): number | undefined {
+  if (currentFrame?.computed) {
+    return currentFrame.computed.getDependenciesCount();
+  }
+  return undefined;
+}
+
+export function getDependencies(): AnySubscribable[] | undefined {
+  if (currentFrame?.computed) {
+    return currentFrame.computed.getDependencies();
+  }
+  return undefined;
+}
+
+export function isInitial(): boolean | undefined {
+  if (currentFrame) {
+    return currentFrame.isInitial;
+  }
+  return undefined;
+}
+
+export function getCurrentComputed(): TrackingFrame['computed'] | undefined {
+  return currentFrame?.computed;
+}

package/src/disposable.ts

@@ -0,0 +1,36 @@
+export interface Disposable {
+  dispose(): void;
+}
+
+export class DisposableGroup implements Disposable {
+  private _disposables: Disposable[] = [];
+  private _isDisposed = false;
+
+  add<T extends Disposable>(disposable: T): T {
+    if (this._isDisposed) {
+      disposable.dispose();
+      return disposable;
+    }
+    this._disposables.push(disposable);
+    return disposable;
+  }
+
+  dispose(): void {
+    if (!this._isDisposed) {
+      this._isDisposed = true;
+      const items = this._disposables;
+      this._disposables = [];
+      for (let i = 0; i < items.length; i++) {
+        items[i].dispose();
+      }
+    }
+  }
+
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  get count(): number {
+    return this._disposables.length;
+  }
+}

package/src/domData.ts

@@ -0,0 +1,42 @@
+const dataStore = new WeakMap<object, Map<string, unknown>>();
+let nextId = 0;
+
+export function domDataGet(node: object, key: string): unknown {
+  return dataStore.get(node)?.get(key);
+}
+
+export function domDataSet(node: object, key: string, value: unknown): void {
+  if (value === undefined) {
+    const data = dataStore.get(node);
+    if (data) {
+      data.delete(key);
+      if (data.size === 0) dataStore.delete(node);
+    }
+    return;
+  }
+  let data = dataStore.get(node);
+  if (!data) {
+    data = new Map();
+    dataStore.set(node, data);
+  }
+  data.set(key, value);
+}
+
+export function domDataGetOrSet(node: object, key: string, value: unknown): unknown {
+  let data = dataStore.get(node);
+  if (!data) {
+    data = new Map();
+    dataStore.set(node, data);
+  }
+  if (data.has(key)) return data.get(key);
+  data.set(key, value);
+  return value;
+}
+
+export function domDataClear(node: object): boolean {
+  return dataStore.delete(node);
+}
+
+export function domDataNextKey(): string {
+  return `__tapout_${nextId++}`;
+}