docs — cmd() · dcmd()

// ── A. one command expression per row ─────────────────────────────────────────
const Row = (t: Todo) => (
  <div class={`row ${t.done ? "done" : ""}`} data-todo-id={t.id}>
    <button class="tick" data-on:click={cmd(toggle, { id: t.id })}>
      {t.done ? "✓" : ""}
    </button>
    <span class="txt">{t.text}</span>
    <span class="owner">{t.owner}</span>
    {t.owner === store().me ? (
      <button class="ico rm" data-on:click={cmd(remove, { id: t.id })}>
        ✕
      </button>
    ) : (
      <span></span>
    )}
  </div>
);

export const SignupForm = () => {
  return (
// No `action` and no `method`: nothing here ever performs a browser submit.
    // The element stays a <form> for what the platform gives you for free —
    // Enter submits, required/type validation runs, labels and focus order work.
    <form class="stack" data-on:submit__prevent={cmd(subscribe)}>
      {/* JSX attribute names cannot contain `.`, so dotted signal paths (and dotted
          event modifiers like __debounce.500ms) go through a spread. */}
      <input
        name="email"
        placeholder="you@example.com"
        {...{ "data-bind:signup.email": true }}
      />
      <select name="plan" {...{ "data-bind:signup.plan": true }}>
        <option value="free">free</option>
        <option value="pro">pro</option>
      </select>
      <input
        name="seats"
        type="number"
        value="1"
        min="1"
        style="width:5.5rem"
        {...{ "data-bind:signup.seats": true }}
      />
      <button class="btn" type="submit">
        subscribe
      </button>
    </form>
);
};

// ── arg codec ────────────────────────────────────────────────────────────────
// One JSON blob in one query param, so types survive the round trip ({id: 42}
// comes back a number). base64url rather than readable JSON specifically so the
// signed path never trips over URL-encoding normalisation.

const enc = (a: unknown) =>
  Buffer.from(JSON.stringify(a)).toString("base64url");

const dec = (b: string) => JSON.parse(Buffer.from(b, "base64url").toString());

/** Resolve a reference, encode its args, and sign them if the command is sealed. */
function mint(ref: Ref, args?: unknown): Minted {
  const id = typeof ref === "string" ? ref : idOf.get(ref);
  if (!id)
    throw new Error(
      `cmd(): not a registered command (did you forget to wrap it in defineCommand()?)`,
    );
  const fn = byId.get(id);
  if (!fn) throw new Error(`cmd(): no command registered as "${id}"`);
  if (args === undefined) {
    if (isSealed(fn))
      throw new Error(`cmd(): "${id}" is sealed but was given no args`);
    return { id, href: `/command/${id}`, sig: "" };
  }
  const b = enc(args);
  if (b.length > maxArgs)
    throw new Error(
      `cmd(): "${id}" args encode to ${b.length} characters, over the ${maxArgs} cap. ` +
        `Args go in the URL, so they are identifiers rather than payloads — keep the ` +
        `data server-side and pass its key. Raise maxArgs at setup if you mean it.`,
    );
  return {
    id,
    href: `/command/${id}?a=${b}`,
    sig: isSealed(fn) ? mac(id, b) : "",
  };
}

/**
 * A reference is either the function itself or its id. Both resolve to the same
 * args type, so `cmd(remove, {id})` and `cmd("todo.remove", {id})` are equally checked
 * — and an unregistered id is a compile error, not a 410 at runtime.
 */
export type Ref = Command<any, any, any> | keyof CommandMap;

/**
 * Builds an id -> args map from a module's exports. Use with `import type`.
 *
 * The `string extends Id` guard drops everything that is not really a command:
 * the phantom brands are optional, so a plain view export like `summarize()`
 * structurally satisfies Command with Id inferred as the wide `string`, which
 * would otherwise collapse the whole map into an index signature.
 */
export type CommandsIn<M> = {
  [
    K in keyof M as M[K] extends Command<any, any, infer Id>
      ? string extends Id
        ? never
        : Id
      : never
  ]: M[K] extends Command<infer A, any, any> ? A : never;
};

/**
 * Args are REQUIRED when the command declares an args schema, optional when it
 * doesn't. Without this, `cmd(remove)` compiles and mints a URL that hands the
 * handler `undefined` — a 500 at click time for a mistake the compiler can see.
 */
type ArgsParam<T> =
  undefined extends ArgsOf<T> ? [args?: ArgsOf<T>] : [args: ArgsOf<T>];

type CmdParams<T> =
  undefined extends ArgsOf<T>
    ? [args?: ArgsOf<T>, opts?: DsOptions]
    : [args: ArgsOf<T>, opts?: DsOptions];

/**
 * cmd() cannot parse signals — it runs at render time, possibly on a different
 * process than the one that will serve the click. But it can read the command's
 * declared scope and narrow what the client sends, so the same declaration that
 * validates on the way in also trims the payload on the way out.
 */
function derivedOpts(ref: Ref): DsOptions | undefined {
  const fn = typeof ref === "string" ? byId.get(ref) : ref;
  const scope = fn && specOf.get(fn)?.scope;
  return scope
    ? { filterSignals: { include: new RegExp(`^${scope}\\.`) } }
    : undefined;
}

// ── scoped input ─────────────────────────────────────────────────────────────
// `scope: "todo"` means: read the $todo.* signal subtree, and have cmd() emit a
// filterSignals so the click stops shipping the entire signal store.

export const add = defineCommand(
  "todo.add",
  { scope: "todo", input: type({ text: "string > 0" }) },
  ({ input, signals, patch }) => {
    store().addTodo(input.text);
    log(
      `scoped input ${JSON.stringify(input)} — client sent only ${JSON.stringify(Object.keys(signals))}`,
      {
        payload: { input, signalKeys: Object.keys(signals) },
      },
    );
    patch.signals({ todo: { text: "" } });
    patch.elements(
      TodoList(),
      DelegatedList(),
      ScopedList(),
      // The row lands in card 03, which is scrolled off the top by the time you
      // are reading card 05 — so the card also shows what it just proved.
      ScopedEcho({ input, keys: Object.keys(signals) }),
    );
  },
);

// ── B. one listener for the whole list ───────────────────────────────────────
// The same two operations, wired the other way. Only the id moves to the
// listener, as a rendered allowlist; the args are still encoded by cmd()'s codec
// at render time, so there is no client-side encoding and sealed commands work.
const rows = dcmd(toggle, remove);

const DRow = (t: Todo) => (
  <div class={`row ${t.done ? "done" : ""}`} data-todo-id={t.id}>
    <button class="tick" {...rows.for(toggle, { id: t.id })}>
      {t.done ? "✓" : ""}
    </button>
    <span class="txt">{t.text}</span>
    <span class="owner">{t.owner}</span>
    {t.owner === store().me ? (
      <button class="ico rm" {...rows.for(remove, { id: t.id })}>
        ✕
      </button>
    ) : (
      <span></span>
    )}
  </div>
);

/** Bytes each style spends per row, measured on the real rendered markup. */
export const rowCost = (): {
  perRow: number;
  delegated: number;
  listener: number;
} => {
  const a =
    ` data-on:click="${cmd(toggle, { id: 1 })}"`.length +
    ` data-on:click="${cmd(remove, { id: 1 })}"`.length;
  // measured on the attributes dcmd() actually emits, both controls
  const attrs = (fn: typeof toggle | typeof remove) =>
    Object.entries(rows.for(fn, { id: 1 }))
      .map(([k, v]) => ` ${k}="${v}"`.length)
      .reduce((x, y) => x + y, 0);
  return {
    perRow: a,
    delegated: attrs(toggle) + attrs(remove),
    listener: ` data-on:click="${rows.on}"`.length,
  };
};

function expr(m: string, ref: Ref, args?: unknown, opts?: DsOptions) {
  const { href, sig } = mint(ref, args);
  const merged = {
    ...(sig || requireHeader ? { headers: { [SIG_HEADER]: sig } } : null),
    ...derivedOpts(ref),
    ...opts, // explicit opts win
  };
  const has = Object.keys(merged).length > 0;
  return has ? `@${m}('${href}', ${js(merged)})` : `@${m}('${href}')`;
}

/** Serialise Datastar options to a JS expression — JSON.stringify would eat the regexes. */
function js(v: unknown): string {
  if (v instanceof RegExp) return v.toString();
  // Single quotes, to match the `@post('…')` around them — JSON.stringify would
  // mix `"` into an expression that is otherwise entirely single-quoted, and
  // every one of those becomes a `"` once it is an attribute value.
  if (typeof v === "string")
    return `'${v.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
  if (Array.isArray(v)) return `[${v.map(js).join(", ")}]`;
  if (v && typeof v === "object") {
    return `{${Object.entries(v)
      // `Command-Signature` is not an identifier, so a bare key would emit
      // a subtraction and Datastar would fail to parse the expression.
      .map(([k, x]) => `${IDENT.test(k) ? k : `'${k}'`}: ${js(x)}`)
      .join(", ")}}`;
  }
  return JSON.stringify(v);
}