docs — defineCommand()

export const ping = defineCommand("demo.ping", ({ patch }) => {
  log("no args, no input");
  patch.elements(
    <code id="ping-out" class="mono" style="color:var(--aqua)">
      pong @ {new Date().toISOString().slice(11, 23)}
    </code>,
  );
});

/**
 * Exported, used by the view, reachable from a test — and NOT an endpoint, because
 * only defineCommand() registers. Under a "use server" directive this export would be a
 * public unauthenticated route.
 */
export const summarize = () =>
  `${store().doneCount()}/${store().todos().length} done`;

const Id = type({ id: "number" });

export const toggle = defineCommand(
  "todo.toggle",
  { args: Id },
  ({ args, patch }) => {
    const todo = store().findTodo(args.id);
    if (!todo) return log(`no such row ${args.id}`, { level: "refusal" });
    store().toggleTodo(args.id);
    log(`args decoded ${JSON.stringify(args)} — a number, not "${args.id}"`, {
      payload: { args },
    });
    patch.elements(TodoList(), DelegatedList(), ScopedList());
  },
);

export const remove = defineCommand(
  "todo.remove",
  { args: Id },
  ({ args, patch }) => {
    const todo = store().findTodo(args.id);
    if (!todo) return log(`no such row ${args.id}`, { level: "refusal" });

    // The client can put any id here — see the "forge" button on the page. The
    // HMAC would not help; only this check does.
    if (todo.owner !== store().me) {
      log(`not your row — refused (owner: ${todo.owner})`, {
        level: "refusal",
        payload: { args, owner: todo.owner, me: store().me },
      });
      patch.elements(
        <Flash tone="bad">
          refused: row {args.id} belongs to {todo.owner}
        </Flash>,
      );
      return;
    }

    store().removeTodo(args.id);
    log(`authorized and removed row ${args.id}`, { payload: { args } });
    patch.elements(
      TodoList(),
      DelegatedList(),
      ScopedList(),
      <Flash tone="ok">removed row {args.id}</Flash>,
    );
  },
);

export const increment = defineCommand(
  "demo.increment",
  { input: type({ "count?": "number" }) },
  ({ input, signals, patch }) => {
    const next = (input.count ?? 0) + 1;
    // `signals` is everything the client sent; `input` is the validated slice.
    log(`whole store rode along — ${Object.keys(signals).length} signals`, {
      payload: { input, signalKeys: Object.keys(signals) },
    });
    patch.signals({ count: next });
  },
);

// CASE 3 — validation failure. Both fields are required, and the page never
// defines $step, so this 422s until you set it. Missing input becomes a refusal
// at the boundary rather than NaN arriving in the handler.
export const strictIncrement = defineCommand(
  "demo.strictIncrement",
  { input: type({ count: "number", step: "number" }) },
  ({ input, patch }) => {
    log(`passed validation — patching $count → ${input.count + input.step}`, {
      payload: { input },
    });
    patch.signals({ count: input.count + input.step });
  },
);

// ── 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) }),
    );
  },
);

const Signup = type({
  email: "string.email",
  plan: "'free' | 'pro'",
  seats: "number | string.numeric.parse",
});

export const subscribe = defineCommand(
  "news.subscribe",
  { scope: "signup", input: Signup },
  ({ input, patch }) => {
    store().addSub(input.email, `${input.plan} ×${input.seats}`);
    log(`seats arrived as a ${typeof input.seats} and validated to a number`, {
      payload: { input, seatsType: typeof input.seats },
    });
    patch.elements(<Subscribers />);
  },
);

const cart = group("cart", () => <CartView />);

export const addLine = cart.defineCommand(
  "add",
  { input: type({ item: "string > 0" }) },
  ({ input }) => {
    store().addToCart(input.item);
    log(`command: add "${input.item}" — the view re-renders itself`);
  },
);

export const bump = cart.defineCommand(
  "bump",
  { args: type({ id: "number", by: "-1 | 1" }) },
  ({ args }) => {
    store().bumpCart(args.id, args.by);
    log(`command: qty ${args.by > 0 ? "+" : ""}${args.by} on line ${args.id}`);
  },
);

export const clear = cart.defineCommand("clear", () => {
  store().clearCart();
  log("command: clear");
});

export type StandardSchemaV1<Input = unknown, Output = Input> = {
  readonly "~standard": {
    readonly version: 1;
    readonly vendor: string;
    readonly validate: (
      value: unknown,
    ) => StandardResult<Output> | Promise<StandardResult<Output>>;
    readonly types?:
      { readonly input: Input; readonly output: Output } | undefined;
  };
};

// ── ArkType ──────────────────────────────────────────────────────────────────
const ArkCoupon = type({
  code: "string >= 4",
  percent: "number | string.numeric.parse",
});

export const arkCheck = defineCommand(
  "coupon.ark",
  { scope: "coupon", input: ArkCoupon },
  ({ input, patch }) => {
    log(`arktype accepted ${JSON.stringify(input)}`, {
      payload: { vendor: "arktype", input, percentType: typeof input.percent },
    });
    patch.elements(
      <Verdict vendor="arktype" ok={true} detail={JSON.stringify(input)} />,
    );
  },
);

// ── Valibot — same slot, same Ctx, no change to commands.ts ───────────────────
const ValCoupon = v.object({
  code: v.pipe(v.string(), v.minLength(4)),
  percent: v.union([v.number(), v.pipe(v.string(), v.transform(Number))]),
});

export const valibotCheck = defineCommand(
  "coupon.valibot",
  { scope: "coupon", input: ValCoupon },
  ({ input, patch }) => {
    log(`valibot accepted ${JSON.stringify(input)}`, {
      payload: { vendor: "valibot", input, percentType: typeof input.percent },
    });
    patch.elements(
      <Verdict vendor="valibot" ok={true} detail={JSON.stringify(input)} />,
    );
  },
);

export const grantRole = defineCommand(
  "admin.grantRole",
  sealed({ args: type({ role: "'viewer' | 'editor' | 'admin'" }) }),
  ({ args, patch }) => {
    store().setRole(args.role);
    log(`sealed args verified — role is now ${args.role}`, {
      payload: { args, verified: true },
    });
    patch.elements(<RoleBadge />);
  },
);

export type Ctx<A = undefined, I = undefined> = {
  /** Render-time arguments baked into the URL by cmd(). Client-visible; forgeable unless sealed. */
  args: A;
  /** Validated per-request input, read from the signals this command declared a scope for. */
  input: I;
  /** Raw. Every non-underscore Datastar signal rides along with every request for free. */
  signals: Record<string, any>;
  req: Request;
  /** Patches back to the client, over the stream this request is answered on. */
  patch: Patch;
};

// Not `Promise<Renderable>`: a self-referential thenable is TS error 1062.
export type Renderable = RenderNode | Promise<RenderNode>;

/**
 * What handlers actually get. The SSE layer speaks strings — `patchSignals`
 * takes serialized JSON and `patchElements` takes markup — which pushes a
 * `JSON.stringify` and a `.html` onto every call site. That ceremony is noise:
 * the handler already has the object and the node. So `ctx.patch` is this, and
 * the raw generator stays available for the options the sugar does not cover.
 */
export type Patch = {
  /** One patch per node. `patch.elements(...lists(), <Flash />)`. */
  elements(...nodes: Renderable[]): Promise<void>;
  /** `patch.signals({ count: 3 })` — serialized for you. */
  signals(
    values: Record<string, unknown> | string,
    options?: Record<string, unknown>,
  ): Promise<void>;
  /** Remove by CSS selector. */
  remove(selector: string): Promise<void>;
  /** Run a script on the client. */
  script(js: string, options?: Record<string, unknown>): Promise<void>;
  /** The underlying generator, for selector/mode/namespace and friends. */
  raw: SsePatch;
};

export const runImport = defineCommand("demo.stream", async ({ patch }) => {
  for (let i = 0; i < STEPS.length; i++) {
    // Each send() writes into the already-open response.
    patch.elements(<Progress at={i + 1} />);
    await Bun.sleep(420);
  }
  log(`streamed ${STEPS.length} patches down one open response`, {
    payload: { steps: STEPS, patches: STEPS.length },
  });
});

/**
 * Annotate the request currently in flight. Handlers import this like any other
 * helper — the request it belongs to comes from async context rather than a
 * parameter threaded through every signature.
 */
export const log = (
  msg: string,
  extra?: { level?: Level; payload?: unknown },
) => void als.getStore()?.lines.push({ msg, ...extra });