@thomas-siegfried/tapout 0.0.1

package/src/domNodeDisposal.ts

@@ -0,0 +1,94 @@
+import { domDataGet, domDataSet, domDataClear, domDataNextKey } from './domData.js';
+import { ignore } from './dependencyDetection.js';
+
+type DisposeCallback = (node: Node) => void;
+
+const disposeCallbacksKey = domDataNextKey();
+
+const CLEANABLE: Record<number, boolean> = { 1: true, 8: true, 9: true };
+const CLEANABLE_WITH_DESCENDANTS: Record<number, boolean> = { 1: true, 9: true };
+
+function getCallbacks(node: Node, create: true): DisposeCallback[];
+function getCallbacks(node: Node, create: false): DisposeCallback[] | undefined;
+function getCallbacks(node: Node, create: boolean): DisposeCallback[] | undefined {
+  let callbacks = domDataGet(node, disposeCallbacksKey) as DisposeCallback[] | undefined;
+  if (!callbacks && create) {
+    callbacks = [];
+    domDataSet(node, disposeCallbacksKey, callbacks);
+  }
+  return callbacks;
+}
+
+function destroyCallbacks(node: Node): void {
+  domDataSet(node, disposeCallbacksKey, undefined);
+}
+
+function cleanSingleNode(node: Node): void {
+  const callbacks = getCallbacks(node, false);
+  if (callbacks) {
+    const snapshot = callbacks.slice(0);
+    for (let i = 0; i < snapshot.length; i++) {
+      snapshot[i](node);
+    }
+  }
+
+  domDataClear(node);
+
+  if (CLEANABLE_WITH_DESCENDANTS[node.nodeType]) {
+    cleanNodesInList(node.childNodes, true);
+  }
+}
+
+function cleanNodesInList(nodeList: ArrayLike<Node>, onlyComments?: boolean): void {
+  const cleaned: Node[] = [];
+  let lastCleaned: Node;
+  for (let i = 0; i < nodeList.length; i++) {
+    if (!onlyComments || nodeList[i].nodeType === 8) {
+      cleanSingleNode(cleaned[cleaned.length] = lastCleaned = nodeList[i]);
+      if (nodeList[i] !== lastCleaned) {
+        while (i-- && cleaned.indexOf(nodeList[i]) === -1) { /* adjust index */ }
+      }
+    }
+  }
+}
+
+export function addDisposeCallback(node: Node, callback: DisposeCallback): void {
+  if (typeof callback !== 'function') {
+    throw new Error('Callback must be a function');
+  }
+  getCallbacks(node, true).push(callback);
+}
+
+export function removeDisposeCallback(node: Node, callback: DisposeCallback): void {
+  const callbacks = getCallbacks(node, false);
+  if (callbacks) {
+    const index = callbacks.indexOf(callback);
+    if (index >= 0) {
+      callbacks.splice(index, 1);
+      if (callbacks.length === 0) {
+        destroyCallbacks(node);
+      }
+    }
+  }
+}
+
+export function cleanNode(node: Node): Node {
+  ignore(() => {
+    if (CLEANABLE[node.nodeType]) {
+      cleanSingleNode(node);
+
+      if (CLEANABLE_WITH_DESCENDANTS[node.nodeType]) {
+        const descendants = (node as Element).getElementsByTagName('*');
+        cleanNodesInList(descendants);
+      }
+    }
+  });
+  return node;
+}
+
+export function removeNode(node: Node): void {
+  cleanNode(node);
+  if (node.parentNode) {
+    node.parentNode.removeChild(node);
+  }
+}

package/src/effects.ts

@@ -0,0 +1,29 @@
+import { PureComputed } from './computed.js';
+
+export interface EffectHandle {
+  dispose(): void;
+}
+
+/**
+ * Track reactive dependencies in `fn` and call `act` whenever they change.
+ * Returns a handle to stop the effect.
+ */
+export function observe<T>(fn: () => T, act: (val: T) => void): EffectHandle {
+  const computed = new PureComputed(fn);
+  computed.extend({ notify: 'always' });
+  const subscription = computed.subscribe(act);
+  return {
+    dispose() {
+      subscription.dispose();
+      computed.dispose();
+    },
+  };
+}
+
+/**
+ * Same as `observe`, but also runs `act` immediately with the current value.
+ */
+export function effect<T>(fn: () => T, act: (val: T) => void): EffectHandle {
+  act(fn());
+  return observe(fn, act);
+}

package/src/event.ts

@@ -0,0 +1,173 @@
+import { addDisposeCallback } from './domNodeDisposal.js';
+
+export type EventCallback<T> = (value: T) => void;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Constructor<T> = abstract new (...args: any[]) => T;
+
+interface SubscriptionEntry<T> {
+  callback: EventCallback<T>;
+  disposed: boolean;
+}
+
+export class EventSubscription {
+  private _disposeCallback: (() => void) | null;
+  private _isDisposed = false;
+
+  constructor(disposeCallback: () => void) {
+    this._disposeCallback = disposeCallback;
+  }
+
+  dispose(): void {
+    if (!this._isDisposed) {
+      this._isDisposed = true;
+      this._disposeCallback!();
+      this._disposeCallback = null;
+    }
+  }
+
+  get closed(): boolean {
+    return this._isDisposed;
+  }
+
+  disposeWhenNodeIsRemoved(node: Node): void {
+    addDisposeCallback(node, () => this.dispose());
+  }
+}
+
+export class EventSubscribable<T = unknown> {
+  #entries: SubscriptionEntry<T>[] = [];
+  #isDisposed = false;
+
+  subscribe(callback: EventCallback<T>): EventSubscription {
+    if (this.#isDisposed) {
+      throw new Error('EventSubscribable is disposed');
+    }
+    const entry: SubscriptionEntry<T> = { callback, disposed: false };
+    this.#entries.push(entry);
+    return new EventSubscription(() => {
+      entry.disposed = true;
+      const idx = this.#entries.indexOf(entry);
+      if (idx !== -1) {
+        this.#entries.splice(idx, 1);
+      }
+    });
+  }
+
+  on<U extends T>(type: Constructor<U>): EventSubscribable<U> {
+    return new FilteredEventSubscribable<T, U>(this, type);
+  }
+
+  get subscriberCount(): number {
+    return this.#entries.length;
+  }
+
+  /** @internal */
+  _emit(value: T): void {
+    if (this.#isDisposed) return;
+    const snapshot = this.#entries.slice();
+    for (let i = 0; i < snapshot.length; i++) {
+      if (!snapshot[i].disposed) {
+        snapshot[i].callback(value);
+      }
+    }
+  }
+
+  /** @internal */
+  _dispose(): void {
+    this.#isDisposed = true;
+    this.#entries.length = 0;
+  }
+}
+
+class FilteredEventSubscribable<T, U extends T> extends EventSubscribable<U> {
+  private _parent: EventSubscribable<T>;
+  private _type: Constructor<U>;
+
+  constructor(parent: EventSubscribable<T>, type: Constructor<U>) {
+    super();
+    this._parent = parent;
+    this._type = type;
+  }
+
+  override subscribe(callback: EventCallback<U>): EventSubscription {
+    return this._parent.subscribe((value: T) => {
+      if (value instanceof this._type) {
+        callback(value as U);
+      }
+    });
+  }
+
+  override on<V extends U>(type: Constructor<V>): EventSubscribable<V> {
+    return new FilteredEventSubscribable<T, V>(this._parent, type);
+  }
+}
+
+export class Event<T = unknown> {
+  private _subscribable: EventSubscribable<T>;
+  private _isDisposed = false;
+
+  constructor() {
+    this._subscribable = new EventSubscribable<T>();
+  }
+
+  get subscribable(): EventSubscribable<T> {
+    return this._subscribable;
+  }
+
+  emit(value: T): void {
+    if (this._isDisposed) {
+      throw new Error('Event is disposed');
+    }
+    this._subscribable._emit(value);
+  }
+
+  dispose(): void {
+    if (!this._isDisposed) {
+      this._isDisposed = true;
+      this._subscribable._dispose();
+    }
+  }
+
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+}
+
+export class AggregateEvent<T = unknown> extends Event<T> {
+  private _pipedSubscriptions: EventSubscription[] = [];
+
+  pipe(...sources: EventSubscribable<T>[]): EventSubscription[] {
+    const newSubs: EventSubscription[] = [];
+    for (const source of sources) {
+      const sub = source.subscribe((value: T) => {
+        this.emit(value);
+      });
+      this._pipedSubscriptions.push(sub);
+      newSubs.push(sub);
+    }
+    return newSubs;
+  }
+
+  override dispose(): void {
+    for (const sub of this._pipedSubscriptions) {
+      if (!sub.closed) {
+        sub.dispose();
+      }
+    }
+    this._pipedSubscriptions.length = 0;
+    super.dispose();
+  }
+}
+
+export function isEvent(value: unknown): value is Event {
+  return value instanceof Event;
+}
+
+export function isEventSubscribable(value: unknown): value is EventSubscribable {
+  return value instanceof EventSubscribable;
+}
+
+export function isAggregateEvent(value: unknown): value is AggregateEvent {
+  return value instanceof AggregateEvent;
+}

package/src/expressionRewriting.ts

@@ -0,0 +1,219 @@
+import { Observable } from './observable.js';
+import { Computed } from './computed.js';
+import { isSubscribable } from './subscribable.js';
+
+// ---- Types ----
+
+export interface KeyValuePair {
+  key?: string;
+  value?: string;
+  unknown?: string;
+}
+
+export interface PreProcessOptions {
+  valueAccessors?: boolean;
+  bindingParams?: boolean;
+  getBindingHandler?: (key: string) => { preprocess?(val: string, key: string, addBinding: (key: string, val: string) => void): string | void } | undefined;
+}
+
+export interface AllBindingsAccessor {
+  get(key: string): unknown;
+  has(key: string): boolean;
+}
+
+// ---- Two-way binding registry ----
+
+export const twoWayBindings: Record<string, boolean | string> = {};
+
+// ---- Token regex ----
+
+const javaScriptReservedWords = ['true', 'false', 'null', 'undefined'];
+
+// Matches something assignable: an isolated identifier or something ending with a property accessor.
+const javaScriptAssignmentTarget = /^(?:[$_a-z][$\w]*|(.+)(\.\s*[$_a-z][$\w]*|\[.+\]))$/i;
+
+const specials = ',"\'`{}()/:[\\]';
+const bindingToken = RegExp([
+  '"(?:\\\\.|[^"])*"',              // double-quoted string
+  "'(?:\\\\.|[^'])*'",              // single-quoted string
+  '`(?:\\\\.|[^`])*`',             // template literal
+  '/\\*(?:[^*]|\\*+[^*/])*\\*+/',  // block comment
+  '//.*\n',                         // line comment
+  '/(?:\\\\.|[^/])+/\\w*',          // regex literal
+  '[^\\s:,/][^' + specials + ']*[^\\s' + specials + ']', // multi-char token
+  '[^\\s]',                         // single char
+].join('|'), 'g');
+
+const divisionLookBehind = /[\])"'A-Za-z0-9_$]+$/;
+const keywordRegexLookBehind: Record<string, number> = { 'in': 1, 'return': 1, 'typeof': 1 };
+
+// ---- Core functions ----
+
+function getWriteableValue(expression: string): string | false {
+  if (javaScriptReservedWords.indexOf(expression) >= 0) return false;
+  const match = expression.match(javaScriptAssignmentTarget);
+  if (match === null) return false;
+  return match[1] ? ('Object(' + match[1] + ')' + match[2]) : expression;
+}
+
+export function parseObjectLiteral(objectLiteralString: string): KeyValuePair[] {
+  let str = objectLiteralString.trim();
+
+  // Strip surrounding braces
+  if (str.charCodeAt(0) === 123 /* { */) str = str.slice(1, -1);
+
+  // Append newline + comma so the last pair terminates uniformly
+  str += '\n,';
+
+  const toks = str.match(bindingToken);
+  const result: KeyValuePair[] = [];
+
+  if (!toks || toks.length <= 1) return result;
+
+  let key: string | undefined;
+  let values: string[] = [];
+  let depth = 0;
+
+  for (let i = 0, tok: string; (tok = toks[i]); ++i) {
+    const c = tok.charCodeAt(0);
+
+    if (c === 44 /* , */) {
+      if (depth <= 0) {
+        result.push(
+          (key && values.length)
+            ? { key, value: values.join('') }
+            : { unknown: key || values.join('') },
+        );
+        key = undefined;
+        depth = 0;
+        values = [];
+        continue;
+      }
+    } else if (c === 58 /* : */) {
+      if (!depth && !key && values.length === 1) {
+        key = values.pop()!;
+        continue;
+      }
+    } else if (c === 47 /* / */ && tok.length > 1 && (tok.charCodeAt(1) === 47 || tok.charCodeAt(1) === 42)) {
+      // Line or block comment — skip
+      continue;
+    } else if (c === 47 /* / */ && i && tok.length > 1) {
+      // Disambiguate regex vs division
+      const prevMatch = toks[i - 1].match(divisionLookBehind);
+      if (prevMatch && !keywordRegexLookBehind[prevMatch[0]]) {
+        str = str.substr(str.indexOf(tok) + 1);
+        const newToks = str.match(bindingToken);
+        if (newToks) {
+          toks.length = 0;
+          toks.push(...newToks);
+        }
+        i = -1;
+        tok = '/';
+      }
+    } else if (c === 40 || c === 123 || c === 91) {
+      // ( { [
+      ++depth;
+    } else if (c === 41 || c === 125 || c === 93) {
+      // ) } ]
+      --depth;
+    } else if (!key && !values.length && (c === 34 || c === 39)) {
+      // Quoted key — strip quotes
+      tok = tok.slice(1, -1);
+    }
+
+    values.push(tok);
+  }
+
+  if (depth > 0) {
+    throw new Error('Unbalanced parentheses, braces, or brackets');
+  }
+
+  return result;
+}
+
+export function preProcessBindings(
+  bindingsStringOrKeyValueArray: string | KeyValuePair[],
+  options?: PreProcessOptions,
+): string {
+  options = options || {};
+
+  const resultStrings: string[] = [];
+  const propertyAccessorResultStrings: string[] = [];
+  const makeValueAccessors = options.valueAccessors;
+  const bindingParams = options.bindingParams;
+  const getBindingHandler = options.getBindingHandler;
+
+  const keyValueArray = typeof bindingsStringOrKeyValueArray === 'string'
+    ? parseObjectLiteral(bindingsStringOrKeyValueArray)
+    : bindingsStringOrKeyValueArray;
+
+  function processKeyValue(key: string, val: string) {
+    let writableVal: string | false;
+
+    function callPreprocessHook(
+      obj: { preprocess?(val: string, key: string, addBinding: (key: string, val: string) => void): string | void } | undefined,
+    ): boolean {
+      if (obj && obj.preprocess) {
+        const result = obj.preprocess(val, key, processKeyValue);
+        if (result !== undefined) val = result;
+        return result !== undefined;
+      }
+      return true;
+    }
+
+    if (!bindingParams) {
+      if (getBindingHandler && !callPreprocessHook(getBindingHandler(key))) return;
+
+      if (twoWayBindings[key] && (writableVal = getWriteableValue(val))) {
+        const writeKey = typeof twoWayBindings[key] === 'string' ? twoWayBindings[key] as string : key;
+        propertyAccessorResultStrings.push("'" + writeKey + "':function(_z){" + writableVal + '=_z}');
+      }
+    }
+
+    if (makeValueAccessors) {
+      val = 'function(){return ' + val + ' }';
+    }
+
+    resultStrings.push("'" + key + "':" + val);
+  }
+
+  for (const kv of keyValueArray) {
+    processKeyValue(kv.key || kv.unknown || '', kv.value || '');
+  }
+
+  if (propertyAccessorResultStrings.length) {
+    processKeyValue('_tap_property_writers', '{' + propertyAccessorResultStrings.join(',') + ' }');
+  }
+
+  return resultStrings.join(',');
+}
+
+export function keyValueArrayContainsKey(keyValueArray: KeyValuePair[], key: string): boolean {
+  for (const kv of keyValueArray) {
+    if (kv.key === key) return true;
+  }
+  return false;
+}
+
+export function writeValueToProperty(
+  property: unknown,
+  allBindings: AllBindingsAccessor,
+  key: string,
+  value: unknown,
+  checkIfDifferent?: boolean,
+): void {
+  if (!property || !isSubscribable(property)) {
+    const propWriters = allBindings.get('_tap_property_writers') as Record<string, (v: unknown) => void> | undefined;
+    if (propWriters && propWriters[key]) {
+      propWriters[key](value);
+    }
+  } else if (isWritable(property) && (!checkIfDifferent || property.peek() !== value)) {
+    property.set(value as never);
+  }
+}
+
+function isWritable(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/extenders.ts

@@ -0,0 +1,102 @@
+import type { Subscribable } from './subscribable.js';
+import { valuesArePrimitiveAndEqual } from './subscribable.js';
+import { schedule, cancel } from './tasks.js';
+
+export type ExtenderHandler = (target: Subscribable, value: unknown) => Subscribable | void;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ExtenderMap {
+  notify: 'always';
+  rateLimit: number | RateLimitOptions;
+  deferred: true;
+}
+
+export type ExtenderOptions = Partial<ExtenderMap> & Record<string, unknown>;
+
+const registry: Record<string, ExtenderHandler> = {};
+
+export function registerExtender(name: string, handler: ExtenderHandler): void {
+  registry[name] = handler;
+}
+
+export function getExtenderHandler(name: string): ExtenderHandler | undefined {
+  return registry[name];
+}
+
+export function throttle(callback: () => void, timeout: number): () => void {
+  let timeoutInstance: ReturnType<typeof setTimeout> | undefined;
+  return function () {
+    if (!timeoutInstance) {
+      timeoutInstance = setTimeout(function () {
+        timeoutInstance = undefined;
+        callback();
+      }, timeout);
+    }
+  };
+}
+
+export function debounce(callback: () => void, timeout: number): () => void {
+  let timeoutInstance: ReturnType<typeof setTimeout> | undefined;
+  return function () {
+    clearTimeout(timeoutInstance);
+    timeoutInstance = setTimeout(callback, timeout);
+  };
+}
+
+export interface RateLimitOptions {
+  timeout: number;
+  method?: 'notifyWhenChangesStop' | ((callback: () => void, timeout: number) => () => void);
+}
+
+registerExtender('notify', (target, notifyWhen) => {
+  target.equalityComparer = notifyWhen === 'always'
+    ? undefined
+    : valuesArePrimitiveAndEqual;
+});
+
+registerExtender('rateLimit', (target, options) => {
+  let timeout: number;
+  let method: RateLimitOptions['method'] | undefined;
+
+  if (typeof options === 'number') {
+    timeout = options;
+  } else {
+    const opts = options as RateLimitOptions;
+    timeout = opts.timeout;
+    method = opts.method;
+  }
+
+  target._deferUpdates = false;
+
+  const limitFunction = typeof method === 'function'
+    ? method
+    : method === 'notifyWhenChangesStop' ? debounce : throttle;
+
+  target.limit((callback) => limitFunction(callback, timeout));
+});
+
+registerExtender('deferred', (target, options) => {
+  if (options !== true) {
+    throw new Error("The 'deferred' extender only accepts the value 'true', because it is not supported to turn deferral off once enabled.");
+  }
+
+  if (!target._deferUpdates) {
+    target._deferUpdates = true;
+    target.limit((callback) => {
+      let handle: number;
+      let ignoreUpdates = false;
+      return () => {
+        if (!ignoreUpdates) {
+          cancel(handle);
+          handle = schedule(callback);
+          try {
+            ignoreUpdates = true;
+            target.notifySubscribers(undefined as never, 'dirty');
+          } finally {
+            ignoreUpdates = false;
+          }
+        }
+      };
+    });
+  }
+});

package/src/filters.ts

@@ -0,0 +1,91 @@
+import { addBindingPreprocessor, setFiltersRegistry } from './bindingProvider.js';
+import type { PreprocessFn } from './bindingProvider.js';
+import { unwrapObservable, toJSON } from './utils.js';
+
+// ---- Filter Registry ----
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export const filters: Record<string, Function> = {};
+
+// Register the filters object so binding expressions can access it as $filters
+setFiltersRegistry(filters);
+
+// ---- Filter Preprocessor ----
+
+// Tokenizer regex: matches quoted strings, || (logical OR — not a pipe), single | and :
+// as individual tokens, and any non-whitespace runs between delimiters.
+const TOKEN_REGEX = /"([^"\\]|\\.)*"|'([^'\\]|\\.)*'|\|\||[|:]|[^\s|:"'][^|:"']*[^\s|:"']|[^\s|:"']/g;
+
+// Transforms `expression | filter1 | filter2:arg1:arg2` into
+// `$filters['filter2']($filters['filter1'](expression),arg1,arg2)`
+export const filterPreprocessor: PreprocessFn = function (input: string): string | void {
+  if (input.indexOf('|') === -1) return input;
+
+  const tokens = input.match(TOKEN_REGEX);
+  if (tokens && tokens.length > 1) {
+    tokens.push('|');
+    let result = tokens[0];
+    let lastToken: string | undefined;
+    let inFilters = false;
+    let nextIsFilter = false;
+
+    for (let i = 1; i < tokens.length; i++) {
+      const token = tokens[i];
+      if (token === '|') {
+        if (inFilters) {
+          if (lastToken === ':') result += 'undefined';
+          result += ')';
+        }
+        nextIsFilter = true;
+        inFilters = true;
+      } else {
+        if (nextIsFilter) {
+          result = "$filters['" + token + "'](" + result;
+        } else if (inFilters && token === ':') {
+          if (lastToken === ':') result += 'undefined';
+          result += ',';
+        } else {
+          result += token;
+        }
+        nextIsFilter = false;
+      }
+      lastToken = token;
+    }
+
+    return result;
+  }
+
+  return input;
+};
+
+// Enable the filter preprocessor for a specific binding handler
+export function enableTextFilter(bindingKeyOrHandler: string): void {
+  addBindingPreprocessor(bindingKeyOrHandler, filterPreprocessor);
+}
+
+// ---- Built-in Filters ----
+
+filters['uppercase'] = function (value: unknown): string {
+  return String(unwrapObservable(value) ?? '').toUpperCase();
+};
+
+filters['lowercase'] = function (value: unknown): string {
+  return String(unwrapObservable(value) ?? '').toLowerCase();
+};
+
+filters['default'] = function (value: unknown, defaultValue: unknown): unknown {
+  const unwrapped = unwrapObservable(value);
+  if (typeof unwrapped === 'function') return unwrapped;
+  if (typeof unwrapped === 'string') return unwrapped.trim() === '' ? defaultValue : unwrapped;
+  if (unwrapped == null) return defaultValue;
+  if (Array.isArray(unwrapped) && unwrapped.length === 0) return defaultValue;
+  return unwrapped;
+};
+
+filters['json'] = function (
+  rootObject: unknown,
+  space?: string | number,
+  replacer?: (key: string, value: unknown) => unknown,
+): string {
+  return toJSON(rootObject, replacer, space);
+};