@async/framework 0.1.0

package/src/cache.js

@@ -0,0 +1,145 @@
+const cacheDefinitionKind = Symbol.for("@async/framework.cacheDefinition");
+
+export function defineCache(options = {}) {
+  return {
+    [cacheDefinitionKind]: true,
+    kind: "cache-definition",
+    store: options.store ?? "memory",
+    ttl: options.ttl
+  };
+}
+
+export function createCacheRegistry(initialMap = {}, { now = () => Date.now() } = {}) {
+  const definitions = new Map();
+  const entries = new Map();
+
+  const registry = {
+    register(id, definition = defineCache()) {
+      assertId(id);
+      const normalized = normalizeDefinition(definition);
+      if (definitions.has(id)) {
+        throw new Error(`Cache "${id}" is already registered.`);
+      }
+      definitions.set(id, normalized);
+      return id;
+    },
+
+    registerMany(map) {
+      for (const [id, definition] of Object.entries(map ?? {})) {
+        registry.register(id, definition);
+      }
+      return registry;
+    },
+
+    resolve(id) {
+      assertId(id);
+      return definitions.get(id);
+    },
+
+    get(key) {
+      assertKey(key);
+      const entry = entries.get(key);
+      if (!entry) {
+        return undefined;
+      }
+      if (entry.expiresAt !== undefined && entry.expiresAt <= now()) {
+        entries.delete(key);
+        return undefined;
+      }
+      return entry.value;
+    },
+
+    set(key, value, options = {}) {
+      assertKey(key);
+      const ttl = options.ttl ?? resolvePolicy(key, options.cache)?.ttl;
+      entries.set(key, {
+        value,
+        expiresAt: ttl === undefined ? undefined : now() + ttl
+      });
+      return value;
+    },
+
+    async getOrSet(key, fn, options = {}) {
+      assertKey(key);
+      if (typeof fn !== "function") {
+        throw new TypeError("cache.getOrSet(key, fn) requires a function.");
+      }
+      const cached = registry.get(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const value = await fn();
+      registry.set(key, value, options);
+      return value;
+    },
+
+    delete(key) {
+      assertKey(key);
+      return entries.delete(key);
+    },
+
+    clear(prefix) {
+      if (prefix === undefined) {
+        entries.clear();
+        return registry;
+      }
+      for (const key of [...entries.keys()]) {
+        if (key.startsWith(prefix)) {
+          entries.delete(key);
+        }
+      }
+      return registry;
+    },
+
+    snapshot() {
+      const snapshot = {};
+      for (const [key] of entries) {
+        const value = registry.get(key);
+        if (value !== undefined) {
+          snapshot[key] = value;
+        }
+      }
+      return snapshot;
+    },
+
+    restore(snapshot = {}) {
+      for (const [key, value] of Object.entries(snapshot ?? {})) {
+        registry.set(key, value);
+      }
+      return registry;
+    }
+  };
+
+  registry.registerMany(initialMap);
+  return registry;
+
+  function resolvePolicy(key, explicitId) {
+    if (explicitId !== undefined) {
+      return definitions.get(explicitId);
+    }
+    if (definitions.has(key)) {
+      return definitions.get(key);
+    }
+    const prefix = key.split(":")[0];
+    return definitions.get(prefix);
+  }
+}
+
+function normalizeDefinition(definition) {
+  if (definition?.[cacheDefinitionKind]) {
+    return definition;
+  }
+  return defineCache(definition);
+}
+
+function assertId(id) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("Cache id must be a non-empty string.");
+  }
+}
+
+function assertKey(key) {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new TypeError("Cache key must be a non-empty string.");
+  }
+}

package/src/component.js

@@ -0,0 +1,182 @@
+import { rawHtml, renderTemplate } from "./html.js";
+
+const componentKind = Symbol.for("@async/framework.component");
+let componentCounter = 0;
+
+export function defineComponent(fn) {
+  if (typeof fn !== "function") {
+    throw new TypeError("defineComponent(fn) requires a function.");
+  }
+  Object.defineProperty(fn, componentKind, {
+    configurable: true,
+    value: true
+  });
+  return fn;
+}
+
+export const component = defineComponent;
+
+export function createComponentRegistry(initialMap = {}) {
+  const entries = new Map();
+
+  const registry = {
+    register(id, Component) {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new TypeError("Component id must be a non-empty string.");
+      }
+      if (!isComponent(Component) && typeof Component !== "function") {
+        throw new TypeError(`Component "${id}" must be a component function.`);
+      }
+      if (entries.has(id)) {
+        throw new Error(`Component "${id}" is already registered.`);
+      }
+      entries.set(id, Component);
+      return id;
+    },
+
+    registerMany(map) {
+      for (const [id, Component] of Object.entries(map ?? {})) {
+        registry.register(id, Component);
+      }
+      return registry;
+    },
+
+    resolve(id) {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new TypeError("Component id must be a non-empty string.");
+      }
+      return entries.get(id);
+    }
+  };
+
+  registry.registerMany(initialMap);
+  return registry;
+}
+
+export function isComponent(value) {
+  return Boolean(value?.[componentKind]);
+}
+
+export function renderComponent(Component, props = {}, runtime, parentScope = "component") {
+  if (!isComponent(Component) && typeof Component !== "function") {
+    throw new TypeError("renderComponent(Component) requires a component function.");
+  }
+
+  const scope = `${parentScope}.${componentName(Component)}.${++componentCounter}`;
+  const cleanups = [];
+  const mountHooks = [];
+  const visibleHooks = [];
+  const context = createComponentContext({
+    runtime,
+    scope,
+    cleanups,
+    mountHooks,
+    visibleHooks
+  });
+
+  const output = Component.call(context, props);
+  const html = renderTemplate(output);
+
+  return {
+    html,
+    mount(target) {
+      for (const hook of mountHooks) {
+        const cleanup = hook(target);
+        if (typeof cleanup === "function") {
+          cleanups.push(cleanup);
+        }
+      }
+    },
+    visible(target, observeVisible) {
+      for (const hook of visibleHooks) {
+        const cleanup = observeVisible(target, hook);
+        if (typeof cleanup === "function") {
+          cleanups.push(cleanup);
+        }
+      }
+    },
+    cleanup() {
+      while (cleanups.length > 0) {
+        cleanups.pop()?.();
+      }
+    }
+  };
+}
+
+function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleHooks }) {
+  const { signals, handlers, loader, server, router, cache } = runtime;
+  const context = {
+    scope,
+    signals,
+    handlers,
+    loader,
+    server,
+    router,
+    cache,
+
+    signal(name, initial) {
+      return signals.ensure(scoped(scope, name), initial);
+    },
+
+    computed(name, fn) {
+      const id = scoped(scope, name);
+      const ref = signals.ensure(id, undefined);
+      const cleanup = signals.effect(() => {
+        signals.set(id, fn.call(context));
+      });
+      cleanups.push(cleanup);
+      return ref;
+    },
+
+    asyncSignal(name, fn) {
+      const id = scoped(scope, name);
+      if (!signals.has(id)) {
+        signals.asyncSignal(id, fn);
+      }
+      return signals.ref(id);
+    },
+
+    effect(fn) {
+      const cleanup = signals.effect(() => fn.call(context));
+      cleanups.push(cleanup);
+      return cleanup;
+    },
+
+    handler(name, fn) {
+      const id = scoped(scope, name);
+      handlers.register(id, function runComponentHandler(handlerContext) {
+        return fn.call({ ...context, ...handlerContext }, handlerContext);
+      });
+      return id;
+    },
+
+    render(Child, childProps = {}) {
+      const child = renderComponent(Child, childProps, runtime, scope);
+      cleanups.push(child.cleanup);
+      mountHooks.push((target) => child.mount(target));
+      visibleHooks.push((target) => child.visible(target, loader._observeVisible));
+      return rawHtml(child.html);
+    },
+
+    onMount(fn) {
+      mountHooks.push((target) => fn.call(context, target));
+    },
+
+    onVisible(fn) {
+      visibleHooks.push((target) => fn.call(context, target));
+    }
+  };
+
+  return context;
+}
+
+function scoped(scope, name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("Scoped signal or handler name must be a non-empty string.");
+  }
+  return `${scope}.${name}`;
+}
+
+function componentName(Component) {
+  return Component.displayName || Component.name || "anonymous";
+}

package/src/delay.js

@@ -0,0 +1,30 @@
+export function delay(ms, signal) {
+  if (signal?.aborted) {
+    return Promise.reject(abortReason(signal));
+  }
+
+  return new Promise((resolve, reject) => {
+    let timer = setTimeout(done, ms);
+
+    function done() {
+      timer = undefined;
+      signal?.removeEventListener?.("abort", aborted);
+      resolve();
+    }
+
+    function aborted() {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      timer = undefined;
+      signal?.removeEventListener?.("abort", aborted);
+      reject(abortReason(signal));
+    }
+
+    signal?.addEventListener?.("abort", aborted, { once: true });
+  });
+}
+
+function abortReason(signal) {
+  return signal?.reason ?? new Error("Operation aborted");
+}

package/src/handlers.js

@@ -0,0 +1,175 @@
+import {
+  applyServerResult,
+  defaultInput,
+  resolveServerCommandArguments,
+  unwrapServerResult
+} from "./server.js";
+
+const builtInTokens = new Set(["preventDefault", "stopPropagation", "stopImmediatePropagation"]);
+const builtInHandlers = {
+  preventDefault() {
+    this.event?.preventDefault?.();
+  },
+  stopPropagation() {
+    this.event?.stopPropagation?.();
+  },
+  stopImmediatePropagation() {
+    this.event?.stopImmediatePropagation?.();
+  }
+};
+
+export function createHandlerRegistry(initialMap = {}) {
+  const handlers = new Map();
+
+  const registry = {
+    register(id, fn) {
+      assertId(id);
+      if (typeof fn !== "function") {
+        throw new TypeError(`Handler "${id}" must be a function.`);
+      }
+      if (handlers.has(id)) {
+        throw new Error(`Handler "${id}" is already registered.`);
+      }
+      handlers.set(id, fn);
+      return id;
+    },
+
+    registerMany(map) {
+      for (const [id, fn] of Object.entries(map ?? {})) {
+        registry.register(id, fn);
+      }
+      return registry;
+    },
+
+    resolve(id) {
+      assertId(id);
+      return handlers.get(id);
+    },
+
+    async run(ref, context = {}) {
+      const steps = parseHandlerRef(ref);
+      const results = [];
+      let stopped = false;
+      const runContext = {
+        ...context,
+        handlers: registry,
+        input: context.input ?? defaultInput(context),
+        stop() {
+          stopped = true;
+        }
+      };
+
+      for (const step of steps) {
+        if (stopped) {
+          break;
+        }
+
+        if (step.type === "server") {
+          if (!runContext.server || typeof runContext.server.run !== "function") {
+            throw new Error(`Server command "${step.id}" cannot run without a server registry.`);
+          }
+          const resolved = resolveServerCommandArguments(step.args, runContext);
+          const result = await runContext.server.run(step.id, resolved.args, {
+            ...runContext,
+            signalPaths: resolved.signalPaths,
+            signalValues: resolved.signalValues
+          });
+          await applyServerResult(result, runContext);
+          results.push(unwrapServerResult(result));
+          continue;
+        }
+
+        const handler = registry.resolve(step.id);
+        if (!handler) {
+          throw new Error(`Handler "${step.id}" is not registered.`);
+        }
+        const value = await handler.call(runContext, runContext);
+        if (!(builtInTokens.has(step.id) && handler === builtInHandlers[step.id])) {
+          results.push(value);
+        }
+      }
+
+      return results;
+    }
+  };
+
+  registry.registerMany(builtInHandlers);
+  registry.registerMany(initialMap);
+  return registry;
+}
+
+export function parseHandlerRef(ref) {
+  if (typeof ref !== "string" || ref.trim().length === 0) {
+    throw new TypeError("Handler ref must be a non-empty string.");
+  }
+
+  return ref
+    .split(";")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map(parseCommand);
+}
+
+export function isHandlerToken(value) {
+  return builtInTokens.has(value);
+}
+
+function assertId(id) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("Handler id must be a non-empty string.");
+  }
+}
+
+function parseCommand(command) {
+  if (command.startsWith("server.")) {
+    return parseServerCommand(command);
+  }
+  if (command.includes("(") || command.includes(")")) {
+    throw new Error(`Command "${command}" is not supported.`);
+  }
+  return { type: "handler", id: command };
+}
+
+function parseServerCommand(command) {
+  const open = command.indexOf("(");
+  if (open === -1 || !command.endsWith(")")) {
+    throw new Error(`Server command "${command}" must be called with parentheses.`);
+  }
+
+  const id = command.slice("server.".length, open).trim();
+  if (!isServerCommandId(id)) {
+    throw new Error(`Server command "${command}" has an invalid function id.`);
+  }
+
+  return {
+    type: "server",
+    id,
+    args: parseArguments(command.slice(open + 1, -1))
+  };
+}
+
+function parseArguments(source) {
+  if (source.trim().length === 0) {
+    return [];
+  }
+
+  return source
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map(parseArgument);
+}
+
+function parseArgument(token) {
+  if (!/^[^\s,();]+$/.test(token)) {
+    throw new Error(`Argument "${token}" is not supported.`);
+  }
+  if (token.startsWith("$")) {
+    return { type: "local", name: token };
+  }
+  return { type: "signal", path: token };
+}
+
+function isServerCommandId(id) {
+  return /^[^.\s();]+(?:\.[^.\s();]+)*$/.test(id);
+}

package/src/html.js

@@ -0,0 +1,65 @@
+import { isSignalRef } from "./signals.js";
+
+const templateKind = Symbol.for("@async/framework.template");
+const rawKind = Symbol.for("@async/framework.rawHtml");
+
+export function html(strings, ...values) {
+  return {
+    [templateKind]: true,
+    strings,
+    values
+  };
+}
+
+export function isTemplateResult(value) {
+  return Boolean(value?.[templateKind]);
+}
+
+export function rawHtml(value) {
+  return {
+    [rawKind]: true,
+    html: String(value ?? "")
+  };
+}
+
+export function renderTemplate(value) {
+  if (isTemplateResult(value)) {
+    let output = "";
+    for (let index = 0; index < value.strings.length; index += 1) {
+      output += value.strings[index];
+      if (index < value.values.length) {
+        output += renderValue(value.values[index]);
+      }
+    }
+    return output;
+  }
+  return renderValue(value);
+}
+
+function renderValue(value) {
+  if (value?.[rawKind]) {
+    return value.html;
+  }
+  if (isTemplateResult(value)) {
+    return renderTemplate(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(renderValue).join("");
+  }
+  if (isSignalRef(value)) {
+    return escapeHtml(value.value);
+  }
+  if (value == null || value === false) {
+    return "";
+  }
+  return escapeHtml(value);
+}
+
+export function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}

package/src/index.js

@@ -0,0 +1,12 @@
+export { asyncSignal } from "./async-signal.js";
+export { Async, createApp, defineApp } from "./app.js";
+export { createCacheRegistry, defineCache } from "./cache.js";
+export { component, createComponentRegistry, defineComponent } from "./component.js";
+export { delay } from "./delay.js";
+export { createHandlerRegistry } from "./handlers.js";
+export { html } from "./html.js";
+export { AsyncLoader } from "./loader.js";
+export { createPartialRegistry } from "./partials.js";
+export { createRouteRegistry, createRouter, defineRoute, route } from "./router.js";
+export { createServerProxy, createServerRegistry } from "./server.js";
+export { computed, createSignal, createSignalRegistry, effect, signal } from "./signals.js";