tina4-nodejs 3.13.63 → 3.13.66

package/packages/cli/src/commands/queue.ts

@@ -0,0 +1,325 @@
+/**
+ * CLI command: queue — run queue workers and manage jobs.
+ *
+ * The top-level `queue` command wires straight to the real @tina4/core Queue
+ * (file backend by default; RabbitMQ/Kafka/MongoDB via TINA4_QUEUE_BACKEND).
+ * `stats`, `retry` and `clear` operate on the queue without booting the app or a
+ * database; `work` runs the app's consumer for a topic. Distinct from
+ * `generate queue`, which SCAFFOLDS a consumer file.
+ *
+ *   tina4nodejs queue work  [topic] [--once] [--poll N] [--services DIR]
+ *   tina4nodejs queue stats [topic] [--json]
+ *   tina4nodejs queue retry [topic]
+ *   tina4nodejs queue clear [status] [topic]
+ *
+ * Mirrors the Python master's _queue* handlers (tina4_python/cli/__init__.py).
+ */
+import { readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadEnv } from "../../../core/src/dotenv.js";
+import { Queue } from "../../../core/src/queue.js";
+import type { QueueJob } from "../../../core/src/job.js";
+
+// ── Flag parsing ─────────────────────────────────────────────────────
+//
+// --key value and bare --flag, mirroring the Python master's _parse_flags:
+// `once` and `json` are boolean-only (they never swallow the next token).
+
+const BOOLEAN_FLAGS = new Set(["once", "json"]);
+
+interface ParsedFlags {
+  flags: Record<string, string | boolean>;
+  positional: string[];
+}
+
+function parseFlags(args: string[]): ParsedFlags {
+  const flags: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (BOOLEAN_FLAGS.has(key)) {
+        flags[key] = true;
+        i += 1;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        flags[key] = args[i + 1];
+        i += 2;
+      } else {
+        flags[key] = true;
+        i += 1;
+      }
+    } else {
+      positional.push(arg);
+      i += 1;
+    }
+  }
+  return { flags, positional };
+}
+
+/** A per-job handler declared by a consumer module (receives the job payload). */
+export type QueueHandler = (payload: unknown) => unknown | Promise<unknown>;
+
+/**
+ * Return the per-job handler that a consumer module declares for `topic`.
+ *
+ * A consumer module (e.g. the one `generate queue <topic>` scaffolds) exposes a
+ * default-export config; when its `topic` matches, `queue work` drives the
+ * consumer through that config's per-job `handle` callable — so the worker owns
+ * the poll loop (honouring --poll and the bounded --once drain) instead of the
+ * consumer's own endless loop. Returns the callable, or null when no consumer in
+ * `servicesDir` targets this topic. Mirrors Python's _resolve_queue_handler.
+ */
+export async function resolveQueueHandler(
+  servicesDir: string,
+  topic: string,
+): Promise<QueueHandler | null> {
+  let entries: string[];
+  try {
+    if (!statSync(servicesDir).isDirectory()) return null;
+    entries = readdirSync(servicesDir);
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries.sort()) {
+    if (entry.startsWith("_")) continue;
+    const ext = extname(entry);
+    if (ext !== ".ts" && ext !== ".js") continue;
+
+    const fullPath = join(servicesDir, entry);
+    try {
+      if (!statSync(fullPath).isFile()) continue;
+      const mod = await import(pathToFileURL(fullPath).href);
+      const config = (mod.default ?? mod) as Record<string, unknown> | undefined;
+      if (
+        config &&
+        typeof config === "object" &&
+        config.topic === topic &&
+        typeof config.handle === "function"
+      ) {
+        return config.handle as QueueHandler;
+      }
+    } catch {
+      // A broken sibling must not sink the worker — skip and keep scanning.
+      continue;
+    }
+  }
+  return null;
+}
+
+/** The single available job out of a possible batch yield. */
+function firstJob(yielded: QueueJob | QueueJob[]): QueueJob {
+  return Array.isArray(yielded) ? yielded[0] : yielded;
+}
+
+// ── Subcommands ──────────────────────────────────────────────────────
+
+/**
+ * Run a consumer loop that pops and processes jobs on a topic.
+ *
+ *   tina4nodejs queue work [topic] [--once] [--poll N] [--services DIR]
+ *
+ * Long-running by default (polls every --poll seconds, 1.0 default; Ctrl-C to
+ * stop). --once does a single-pass drain — it processes every currently
+ * available job then exits (poll interval 0). The per-job handler is resolved
+ * from the app's consumer for this topic (see resolveQueueHandler); with no
+ * handler it drains and acks with a warning rather than inventing behaviour.
+ */
+async function queueWork(args: string[]): Promise<void> {
+  loadEnv();
+  const { flags, positional } = parseFlags(args);
+  const topic = positional[0] ?? "default";
+  const once = Boolean(flags.once);
+
+  // --poll is in SECONDS (parity with the Python master); consume() takes ms.
+  let pollSeconds: number;
+  if (once) {
+    pollSeconds = 0; // single-pass: consume() returns as soon as the topic is empty
+  } else {
+    const pollRaw = typeof flags.poll === "string" ? flags.poll.trim() : "";
+    const parsed = Number(pollRaw);
+    pollSeconds = pollRaw && Number.isFinite(parsed) ? parsed : 1.0;
+  }
+
+  let servicesDir =
+    typeof flags.services === "string" && flags.services
+      ? flags.services
+      : process.env.TINA4_SERVICE_DIR || "src/services";
+  if (flags.services === true) servicesDir = process.env.TINA4_SERVICE_DIR || "src/services";
+
+  const handler = await resolveQueueHandler(servicesDir, topic);
+  const queue = new Queue({ topic });
+
+  if (handler === null) {
+    console.log(`  ⚠ No consumer handler found for topic '${topic}' in ${servicesDir}.`);
+    console.log(`    Scaffold one with: tina4nodejs generate queue ${topic}`);
+    console.log("    Draining (consume + ack) without processing.");
+  }
+
+  const mode = once ? "single-pass drain" : `polling every ${pollSeconds}s (Ctrl-C to stop)`;
+  console.log(`  Queue worker on '${topic}' — ${mode}...`);
+
+  let processed = 0;
+  let failed = 0;
+
+  // Long-running mode: Ctrl-C prints the tally and exits cleanly (the poll loop
+  // is idle in setTimeout when interrupted). --once is bounded, so no handler.
+  let onSigint: (() => void) | undefined;
+  if (!once) {
+    onSigint = () => {
+      console.log("\n  Interrupted — stopping worker.");
+      console.log(`  Processed ${processed} job(s), ${failed} failed on '${topic}'.`);
+      process.exit(0);
+    };
+    process.on("SIGINT", onSigint);
+  }
+
+  try {
+    for await (const yielded of queue.consume(topic, undefined, pollSeconds * 1000)) {
+      const job = firstJob(yielded);
+      try {
+        if (handler !== null) await handler(job.payload);
+        job.complete();
+        processed += 1;
+      } catch (err) {
+        job.fail(String(err instanceof Error ? err.message : err));
+        failed += 1;
+      }
+    }
+  } finally {
+    if (onSigint) process.off("SIGINT", onSigint);
+  }
+
+  console.log(`  Processed ${processed} job(s), ${failed} failed on '${topic}'.`);
+}
+
+/**
+ * Print pending / in-flight / failed / dead-letter / completed counts.
+ *
+ *   tina4nodejs queue stats [topic] [--json]
+ */
+async function queueStats(args: string[]): Promise<void> {
+  loadEnv();
+  const { flags, positional } = parseFlags(args);
+  const topic = positional[0] ?? "default";
+
+  const queue = new Queue({ topic });
+  const stats = {
+    topic,
+    pending: queue.size("pending"), // waiting to run
+    reserved: queue.size("reserved"), // popped, not yet acked (in-flight)
+    failed: queue.failed().length, // failed once, still retrying
+    dead: queue.size("dead"), // exhausted retries (dead-letter)
+    completed: queue.size("completed"), // terminal-completed (0 on the file backend)
+  };
+
+  if (flags.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return;
+  }
+
+  console.log(`\n  Queue '${topic}'`);
+  console.log(`    pending    ${stats.pending}`);
+  console.log(`    reserved   ${stats.reserved}    (in-flight)`);
+  console.log(`    failed     ${stats.failed}    (retrying)`);
+  console.log(`    dead       ${stats.dead}    (dead-letter)`);
+  console.log(`    completed  ${stats.completed}`);
+  console.log("");
+}
+
+/**
+ * Re-queue failed and dead-letter jobs so they run again.
+ *
+ *   tina4nodejs queue retry [topic]
+ *
+ * Revives every dead-letter job (manual override, regardless of attempt count)
+ * and re-queues any failed-but-still-eligible jobs.
+ */
+async function queueRetry(args: string[]): Promise<void> {
+  loadEnv();
+  const { positional } = parseFlags(args);
+  const topic = positional[0] ?? "default";
+
+  const queue = new Queue({ topic });
+
+  // maxRetries=0 => every job in the dead-letter store, whatever its attempt
+  // count (matches what stats/size("dead") reports), not only attempts>=N.
+  const dead = queue.deadLetters(0);
+  let revived = 0;
+  for (const job of dead) {
+    if (queue.retry(job.id)) revived += 1;
+  }
+  // Any failed-but-retryable jobs still under the limit (no-op on the file
+  // backend once the above moved them out, meaningful for other backends).
+  const requeued = queue.retryFailed();
+
+  const total = revived + requeued;
+  console.log(
+    `  Re-queued ${total} job(s) on '${topic}' (${revived} dead-letter, ${requeued} failed).`,
+  );
+}
+
+/**
+ * Purge jobs of a given status (default: completed).
+ *
+ *   tina4nodejs queue clear [status] [topic]
+ *
+ * status is one of pending / reserved / completed / failed / dead. The default
+ * 'completed' clears finished jobs; pass e.g. `queue clear pending` or
+ * `queue clear dead orders` to purge another status / topic.
+ */
+async function queueClear(args: string[]): Promise<void> {
+  loadEnv();
+  const { positional } = parseFlags(args);
+  const status = positional[0] ?? "completed";
+  const topic = positional[1] ?? "default";
+
+  const queue = new Queue({ topic });
+  const removed = queue.purge(status);
+  console.log(`  Cleared ${removed} '${status}' job(s) from '${topic}'.`);
+}
+
+// ── Sub-dispatch table ───────────────────────────────────────────────
+//
+// The single source for the queue subcommands — drives dispatch AND the
+// manifest's queue.subcommands (bin.ts COMMANDS). Mirrors Python's
+// _QUEUE_SUBCOMMANDS.
+
+const QUEUE_SUBCOMMANDS: Record<string, (args: string[]) => Promise<void>> = {
+  work: queueWork,
+  stats: queueStats,
+  retry: queueRetry,
+  clear: queueClear,
+};
+
+/** Subcommand names, in order — surfaced in `commands --json` for the tina4 client. */
+export const QUEUE_SUBCOMMAND_NAMES = Object.keys(QUEUE_SUBCOMMANDS);
+
+/**
+ * Top-level queue command: run workers and manage jobs. Dispatches to the
+ * subcommand handlers above; unknown / missing subcommands fail loud (exit 1).
+ */
+export async function queueCommand(args: string[] = []): Promise<void> {
+  const list = QUEUE_SUBCOMMAND_NAMES.join(", ");
+
+  if (!args || args.length === 0) {
+    console.log("Usage: tina4nodejs queue <work|stats|retry|clear> [options]");
+    console.log(`  Subcommands: ${list}`);
+    process.exit(1);
+    return;
+  }
+
+  const sub = args[0].toLowerCase();
+  const handler = QUEUE_SUBCOMMANDS[sub];
+  if (!handler) {
+    console.log(`Unknown queue subcommand: ${sub}`);
+    console.log(`  Available: ${list}`);
+    process.exit(1);
+    return;
+  }
+
+  await handler(args.slice(1));
+}

package/packages/core/public/js/frond.js

@@ -81,6 +81,12 @@ var _frondModule = (() => {
     xhr.onerror = function() {
       if (opts.onError) opts.onError(xhr.status, xhr);
     };
+    if (opts.timeout !== 0) {
+      xhr.timeout = opts.timeout || 3e4;
+      xhr.ontimeout = function() {
+        if (opts.onError) opts.onError(xhr.status, xhr);
+      };
+    }
     xhr.send(body);
   }
   function inject(html, target) {
@@ -123,7 +129,7 @@ var _frondModule = (() => {
     });
     return body.innerHTML;
   }
-  function load(url, target, callback) {
+  function load(url, target, callback, onError) {
     const targetId = target || "content";
     request(url, {
       method: "GET",
@@ -134,10 +140,11 @@ var _frondModule = (() => {
         } else {
           if (callback) callback(data);
         }
-      }
+      },
+      onError
     });
   }
-  function post(url, data, target, callback) {
+  function post(url, data, target, callback, onError) {
     const targetId = target || "content";
     request(url, {
       method: "POST",
@@ -153,7 +160,8 @@ var _frondModule = (() => {
           return;
         }
         if (callback) callback(html, responseData);
-      }
+      },
+      onError
     });
   }
   var form = {
@@ -209,10 +217,11 @@ var _frondModule = (() => {
      * @param url      - URL to POST to.
      * @param target   - DOM id to inject response into (default: "message").
      * @param callback - Optional callback.
+     * @param onError  - Optional error callback — fires on non-2xx, transport error, or timeout.
      */
-    submit: function(formId, url, target, callback) {
+    submit: function(formId, url, target, callback, onError) {
       const data = form.collect(formId);
-      post(url, data, target || "message", callback);
+      post(url, data, target || "message", callback, onError);
     },
     /**
      * Load a form via the given action and inject response HTML.
@@ -224,8 +233,9 @@ var _frondModule = (() => {
      * @param url     - URL to fetch.
      * @param target  - DOM id to inject into (default: "form").
      * @param callback - Optional callback.
+     * @param onError  - Optional error callback — fires on non-2xx, transport error, or timeout.
      */
-    show: function(action, url, target, callback) {
+    show: function(action, url, target, callback, onError) {
       let method = action.toUpperCase();
       if (action === "create" || action === "edit") method = "GET";
       if (action === "delete") method = "DELETE";
@@ -243,7 +253,8 @@ var _frondModule = (() => {
             return;
           }
           if (callback) callback(html);
-        }
+        },
+        onError
       });
     }
   };

package/packages/core/public/js/frond.min.js

@@ -1,2 +1,2 @@
-var _frondModule=(()=>{var E=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var H=Object.prototype.hasOwnProperty;var q=(t,s)=>{for(var e in s)E(t,e,{get:s[e],enumerable:!0})},D=(t,s,e,o)=>{if(s&&typeof s=="object"||typeof s=="function")for(let n of A(s))!H.call(t,n)&&n!==e&&E(t,n,{get:()=>s[n],enumerable:!(o=O(s,n))||o.enumerable});return t};var W=t=>D(E({},"__esModule",{value:!0}),t);var z={};q(z,{frond:()=>L});var y=null;function v(t,s){let e;typeof s=="function"?e={onSuccess:s}:e=s||{};let o=(e.method||"GET").toUpperCase(),n=new XMLHttpRequest;if(n.open(o,t,!0),y!==null&&n.setRequestHeader("Authorization","Bearer "+y),e.headers)for(let u in e.headers)Object.prototype.hasOwnProperty.call(e.headers,u)&&n.setRequestHeader(u,e.headers[u]);let c=null;e.body!==void 0&&e.body!==null&&(e.body instanceof FormData?c=e.body:typeof e.body=="object"?(c=JSON.stringify(e.body),n.setRequestHeader("Content-Type","application/json; charset=UTF-8")):typeof e.body=="string"&&(c=e.body,n.setRequestHeader("Content-Type","text/plain; charset=UTF-8"))),n.onload=function(){let u=n.getResponseHeader("FreshToken");u&&u!==""&&(y=u);let r=n.response;try{r=JSON.parse(r)}catch{}if(n.responseURL){let i=new URL(t,window.location.href).href;if(n.responseURL!==i){window.location.href=n.responseURL;return}}n.status>=200&&n.status<400?e.onSuccess&&e.onSuccess(r,n.status,n):e.onError&&e.onError(n.status,n)},n.onerror=function(){e.onError&&e.onError(n.status,n)},n.send(c)}function h(t,s){if(!t)return"";let e=new DOMParser,o=t.includes("<html>")?t:"<body>"+t+"</body></html>",c=e.parseFromString(o,"text/html").querySelector("body"),u=c.querySelectorAll("script");if(u.forEach(function(r){r.remove()}),s!==null){let r=document.getElementById(s);return r&&(c.children.length>0?r.replaceChildren.apply(r,Array.from(c.children)):r.innerHTML=c.innerHTML,u.forEach(function(i){let l=document.createElement("script");l.type="text/javascript",l.async=!0,i.src?l.src=i.src:l.textContent=i.textContent,r.appendChild(l)})),""}return u.forEach(function(r){let i=document.createElement("script");i.type="text/javascript",i.async=!0,i.textContent=r.textContent,document.body.appendChild(i)}),c.innerHTML}function _(t,s,e){let o=s||"content";v(t,{method:"GET",onSuccess:function(n,c){if(document.getElementById(o)){let u=h(n,o);e&&e(u,n)}else e&&e(n)}})}function R(t,s,e,o){let n=e||"content";v(t,{method:"POST",body:s,onSuccess:function(c){let u="";if(c&&c.message!==void 0)u=h(c.message,n);else if(document.getElementById(n))u=h(c,n);else{o&&o(c);return}o&&o(u,c)}})}var x={collect:function(t){let s=new FormData,e=document.querySelectorAll("#"+t+" select, #"+t+" input, #"+t+" textarea");for(let o=0;o<e.length;o++){let n=e[o];if(n.name==="formToken"&&y!==null&&(n.value=y),!!n.name)if(n.type==="file"){let c=n.files;if(c)for(let u=0;u<c.length;u++){let r=c[u];if(r!==void 0){let i=n.name;c.length>1&&!i.includes("[")&&(i=i+"[]"),s.append(i,r,r.name)}}}else n.type==="checkbox"||n.type==="radio"?n.checked?s.append(n.name,n.value):n.type!=="radio"&&s.append(n.name,"0"):s.append(n.name,n.value===""?"":n.value)}return s},submit:function(t,s,e,o){let n=x.collect(t);R(s,n,e||"message",o)},show:function(t,s,e,o){let n=t.toUpperCase();(t==="create"||t==="edit")&&(n="GET"),t==="delete"&&(n="DELETE");let c=e||"form";v(s,{method:n,onSuccess:function(u){let r="";if(u&&u.message!==void 0)r=h(u.message,c);else if(document.getElementById(c))r=h(u,c);else{o&&o(u);return}o&&o(r)}})}};function M(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,protocols:[],onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",send:function(f){if(!o||o.readyState!==WebSocket.OPEN)throw new Error("[frond] WebSocket is not connected");o.send(typeof f=="string"?f:JSON.stringify(f))},on:function(f,a){return i[f]||(i[f]=[]),i[f].push(a),function(){let d=i[f],g=d.indexOf(a);g>=0&&d.splice(g,1)}},close:function(f,a){n=!0,r&&(clearTimeout(r),r=null),o&&o.close(f||1e3,a||""),l.status="closed"}};function p(f){if(typeof f!="string")return f;try{return JSON.parse(f)}catch{return f}}function m(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,w()},c),c=Math.min(c*2,e.maxReconnectDelay))}function w(){l.status=u>0?"reconnecting":"connecting";try{o=new WebSocket(t,e.protocols)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let f of i.open)f()},o.onmessage=function(f){let a=p(f.data);for(let d of i.message)d(a)},o.onclose=function(f){l.status="closed",e.onClose(f.code,f.reason);for(let a of i.close)a(f.code,f.reason);n||m()},o.onerror=function(f){e.onError(f);for(let a of i.error)a(f)}}return w(),l}function I(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,events:[],json:!0,onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",on:function(a,d){return i[a]||(i[a]=[]),i[a].push(d),function(){let g=i[a],T=g.indexOf(d);T>=0&&g.splice(T,1)}},close:function(){n=!0,r&&(clearTimeout(r),r=null),o&&(o.close(),o=null),l.status="closed"}};function p(a){if(!e.json)return a;try{return JSON.parse(a)}catch{return a}}function m(a,d){for(let g of i.message)g(a,d||void 0)}function w(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,f()},c),c=Math.min(c*2,e.maxReconnectDelay))}function f(){l.status=u>0?"reconnecting":"connecting";try{o=new EventSource(t)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let a of i.open)a(null)},o.onmessage=function(a){m(p(a.data),null)};for(let a of e.events)o.addEventListener(a,function(d){m(p(d.data),a)});o.onerror=function(a){e.onError(a);for(let d of i.error)d(a);if(o&&o.readyState===2){o=null,l.status="closed",e.onClose();for(let d of i.close)d(null);n||w()}}}return f(),l}var U={set:function(t,s,e){let o="";if(e){let n=new Date;n.setTime(n.getTime()+e*24*60*60*1e3),o="; expires="+n.toUTCString()}document.cookie=t+"="+(s||"")+o+"; path=/"},get:function(t){let s=t+"=",e=document.cookie.split(";");for(let o=0;o<e.length;o++){let n=e[o];for(;n.charAt(0)===" ";)n=n.substring(1);if(n.indexOf(s)===0)return n.substring(s.length)}return null},remove:function(t){document.cookie=t+"=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/"}};function j(t,s){let e=document.getElementById("message");if(!e)return;let o=s||"info";e.innerHTML='<div class="alert alert-'+o+' alert-dismissible">'+t+'<button type="button" class="btn-close" data-t4-dismiss="alert">&times;</button></div>'}function B(t,s,e,o){let n=window.screenLeft!==void 0?window.screenLeft:window.screenX,c=window.screenTop!==void 0?window.screenTop:window.screenY,u=window.innerWidth||document.documentElement.clientWidth||screen.width,r=window.innerHeight||document.documentElement.clientHeight||screen.height,i=u/window.screen.availWidth,l=(u-e)/2/i+n,p=(r-o)/2/i+c,m=window.open(t,s,"directories=no,toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width="+e/i+",height="+o/i+",top="+p+",left="+l);return window.focus&&m&&m.focus(),m}function P(t){if(t.indexOf("No data available")>=0){window.alert("No data available for this report.");return}window.open(t,"_blank","toolbar=no,scrollbars=yes,resizable=yes,width=800,height=600,top=0,left=0")}function F(t,s,e,o){v(t,{method:"POST",body:{query:s,variables:e||{}},onSuccess:function(n){o&&o(n.data||null,n.errors||void 0)},onError:function(n){o&&o(null,[{message:"GraphQL request failed with status "+n}])}})}function b(t){let s=t.dataset;return s&&s.key?s.key:null}function X(t,s){let e=s.attributes;for(let n=0;n<e.length;n++){let c=e[n];t.getAttribute(c.name)!==c.value&&t.setAttribute(c.name,c.value)}Array.prototype.slice.call(t.attributes).forEach(function(n){s.hasAttribute(n.name)||t.removeAttribute(n.name)})}function G(t,s){let e=s.tagName;e==="INPUT"||e==="TEXTAREA"||e==="SELECT"||(X(t,s),t.children.length||s.children.length?C(t,s):t.innerHTML!==s.innerHTML&&(t.innerHTML=s.innerHTML))}function C(t,s){let e=Array.prototype.slice.call(t.children),o=Array.prototype.slice.call(s.children),n={};e.forEach(function(r){let i=b(r);i&&(n[i]=r)});let c=[];for(let r=0;r<o.length;r++){let i=o[r],l=b(i),p=null;l&&n[l]?p=n[l]:!l&&e[r]&&!b(e[r])&&e[r].tagName===i.tagName&&(p=e[r]),p&&p.tagName===i.tagName?(G(p,i),reused.push(p),c.push(p)):c.push(i)}let u=t.firstElementChild;for(let r=0;r<c.length;r++){let i=c[r];i===u?u=u.nextElementSibling:t.insertBefore(i,u)}e.forEach(function(r){c.indexOf(r)===-1&&r.parentNode===t&&t.removeChild(r)}),reused}function k(t,s){let e=document.createElement("div");if(e.innerHTML=s,!e.children.length||!t.children.length){t.innerHTML=s;return}C(t,e)}function J(t){return/^wss?:\/\//.test(t)?t:(typeof location<"u"&&location.protocol==="https:"?"wss":"ws")+"://"+location.host+t}function N(t,s){return t&&typeof t=="object"?t.type==="live"?s&&t.name&&t.name!==s?null:t.html!=null?String(t.html):null:null:typeof t=="string"?t:null}function S(t){if(typeof document>"u")return;let e=(t||document).querySelectorAll("[data-frond-live]");Array.prototype.slice.call(e).forEach(function(o){if(o.__frondLive)return;o.__frondLive=!0;let n=o.getAttribute("data-mode"),c=o.getAttribute("data-frond-live");if(n==="poll"){let u=o.getAttribute("data-src"),r=(parseInt(o.getAttribute("data-interval"),10)||5)*1e3,i=setInterval(function(){typeof document<"u"&&document.hidden||v(u,{method:"GET",onSuccess:function(l){k(o,typeof l=="string"?l:String(l))}})},r);o.__frondLiveStop=function(){clearInterval(i)}}else if(n==="ws"){let u=M(J(o.getAttribute("data-ws")));u.on("message",function(r){let i=N(r,c);i!==null&&k(o,i)}),o.__frondLiveStop=function(){u.close()}}else n==="sse"&&typeof console<"u"&&console.warn&&console.warn("[frond.live] sse transport is not wired yet (v1 supports poll and ws); block '"+c+"' shows first paint only. Use poll or ws.")})}var L={request:v,load:_,post:R,inject:h,form:x,ws:M,sse:I,live:S,cookie:U,message:j,popup:B,report:P,graphql:F,get token(){return y},set token(t){y=t}};typeof window<"u"&&(window.frond=L,typeof document<"u"&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){S()}):S()));return W(z);})();
+var _frondModule=(()=>{var E=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var q=Object.prototype.hasOwnProperty;var A=(t,s)=>{for(var e in s)E(t,e,{get:s[e],enumerable:!0})},D=(t,s,e,o)=>{if(s&&typeof s=="object"||typeof s=="function")for(let n of H(s))!q.call(t,n)&&n!==e&&E(t,n,{get:()=>s[n],enumerable:!(o=O(s,n))||o.enumerable});return t};var W=t=>D(E({},"__esModule",{value:!0}),t);var z={};A(z,{frond:()=>C});var y=null;function v(t,s){let e;typeof s=="function"?e={onSuccess:s}:e=s||{};let o=(e.method||"GET").toUpperCase(),n=new XMLHttpRequest;if(n.open(o,t,!0),y!==null&&n.setRequestHeader("Authorization","Bearer "+y),e.headers)for(let u in e.headers)Object.prototype.hasOwnProperty.call(e.headers,u)&&n.setRequestHeader(u,e.headers[u]);let c=null;e.body!==void 0&&e.body!==null&&(e.body instanceof FormData?c=e.body:typeof e.body=="object"?(c=JSON.stringify(e.body),n.setRequestHeader("Content-Type","application/json; charset=UTF-8")):typeof e.body=="string"&&(c=e.body,n.setRequestHeader("Content-Type","text/plain; charset=UTF-8"))),n.onload=function(){let u=n.getResponseHeader("FreshToken");u&&u!==""&&(y=u);let r=n.response;try{r=JSON.parse(r)}catch{}if(n.responseURL){let i=new URL(t,window.location.href).href;if(n.responseURL!==i){window.location.href=n.responseURL;return}}n.status>=200&&n.status<400?e.onSuccess&&e.onSuccess(r,n.status,n):e.onError&&e.onError(n.status,n)},n.onerror=function(){e.onError&&e.onError(n.status,n)},e.timeout!==0&&(n.timeout=e.timeout||3e4,n.ontimeout=function(){e.onError&&e.onError(n.status,n)}),n.send(c)}function h(t,s){if(!t)return"";let e=new DOMParser,o=t.includes("<html>")?t:"<body>"+t+"</body></html>",c=e.parseFromString(o,"text/html").querySelector("body"),u=c.querySelectorAll("script");if(u.forEach(function(r){r.remove()}),s!==null){let r=document.getElementById(s);return r&&(c.children.length>0?r.replaceChildren.apply(r,Array.from(c.children)):r.innerHTML=c.innerHTML,u.forEach(function(i){let l=document.createElement("script");l.type="text/javascript",l.async=!0,i.src?l.src=i.src:l.textContent=i.textContent,r.appendChild(l)})),""}return u.forEach(function(r){let i=document.createElement("script");i.type="text/javascript",i.async=!0,i.textContent=r.textContent,document.body.appendChild(i)}),c.innerHTML}function _(t,s,e,o){let n=s||"content";v(t,{method:"GET",onSuccess:function(c,u){if(document.getElementById(n)){let r=h(c,n);e&&e(r,c)}else e&&e(c)},onError:o})}function k(t,s,e,o,n){let c=e||"content";v(t,{method:"POST",body:s,onSuccess:function(u){let r="";if(u&&u.message!==void 0)r=h(u.message,c);else if(document.getElementById(c))r=h(u,c);else{o&&o(u);return}o&&o(r,u)},onError:n})}var x={collect:function(t){let s=new FormData,e=document.querySelectorAll("#"+t+" select, #"+t+" input, #"+t+" textarea");for(let o=0;o<e.length;o++){let n=e[o];if(n.name==="formToken"&&y!==null&&(n.value=y),!!n.name)if(n.type==="file"){let c=n.files;if(c)for(let u=0;u<c.length;u++){let r=c[u];if(r!==void 0){let i=n.name;c.length>1&&!i.includes("[")&&(i=i+"[]"),s.append(i,r,r.name)}}}else n.type==="checkbox"||n.type==="radio"?n.checked?s.append(n.name,n.value):n.type!=="radio"&&s.append(n.name,"0"):s.append(n.name,n.value===""?"":n.value)}return s},submit:function(t,s,e,o,n){let c=x.collect(t);k(s,c,e||"message",o,n)},show:function(t,s,e,o,n){let c=t.toUpperCase();(t==="create"||t==="edit")&&(c="GET"),t==="delete"&&(c="DELETE");let u=e||"form";v(s,{method:c,onSuccess:function(r){let i="";if(r&&r.message!==void 0)i=h(r.message,u);else if(document.getElementById(u))i=h(r,u);else{o&&o(r);return}o&&o(i)},onError:n})}};function M(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,protocols:[],onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",send:function(f){if(!o||o.readyState!==WebSocket.OPEN)throw new Error("[frond] WebSocket is not connected");o.send(typeof f=="string"?f:JSON.stringify(f))},on:function(f,a){return i[f]||(i[f]=[]),i[f].push(a),function(){let d=i[f],g=d.indexOf(a);g>=0&&d.splice(g,1)}},close:function(f,a){n=!0,r&&(clearTimeout(r),r=null),o&&o.close(f||1e3,a||""),l.status="closed"}};function m(f){if(typeof f!="string")return f;try{return JSON.parse(f)}catch{return f}}function p(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,w()},c),c=Math.min(c*2,e.maxReconnectDelay))}function w(){l.status=u>0?"reconnecting":"connecting";try{o=new WebSocket(t,e.protocols)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let f of i.open)f()},o.onmessage=function(f){let a=m(f.data);for(let d of i.message)d(a)},o.onclose=function(f){l.status="closed",e.onClose(f.code,f.reason);for(let a of i.close)a(f.code,f.reason);n||p()},o.onerror=function(f){e.onError(f);for(let a of i.error)a(f)}}return w(),l}function I(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,events:[],json:!0,onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",on:function(a,d){return i[a]||(i[a]=[]),i[a].push(d),function(){let g=i[a],T=g.indexOf(d);T>=0&&g.splice(T,1)}},close:function(){n=!0,r&&(clearTimeout(r),r=null),o&&(o.close(),o=null),l.status="closed"}};function m(a){if(!e.json)return a;try{return JSON.parse(a)}catch{return a}}function p(a,d){for(let g of i.message)g(a,d||void 0)}function w(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,f()},c),c=Math.min(c*2,e.maxReconnectDelay))}function f(){l.status=u>0?"reconnecting":"connecting";try{o=new EventSource(t)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let a of i.open)a(null)},o.onmessage=function(a){p(m(a.data),null)};for(let a of e.events)o.addEventListener(a,function(d){p(m(d.data),a)});o.onerror=function(a){e.onError(a);for(let d of i.error)d(a);if(o&&o.readyState===2){o=null,l.status="closed",e.onClose();for(let d of i.close)d(null);n||w()}}}return f(),l}var U={set:function(t,s,e){let o="";if(e){let n=new Date;n.setTime(n.getTime()+e*24*60*60*1e3),o="; expires="+n.toUTCString()}document.cookie=t+"="+(s||"")+o+"; path=/"},get:function(t){let s=t+"=",e=document.cookie.split(";");for(let o=0;o<e.length;o++){let n=e[o];for(;n.charAt(0)===" ";)n=n.substring(1);if(n.indexOf(s)===0)return n.substring(s.length)}return null},remove:function(t){document.cookie=t+"=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/"}};function j(t,s){let e=document.getElementById("message");if(!e)return;let o=s||"info";e.innerHTML='<div class="alert alert-'+o+' alert-dismissible">'+t+'<button type="button" class="btn-close" data-t4-dismiss="alert">&times;</button></div>'}function X(t,s,e,o){let n=window.screenLeft!==void 0?window.screenLeft:window.screenX,c=window.screenTop!==void 0?window.screenTop:window.screenY,u=window.innerWidth||document.documentElement.clientWidth||screen.width,r=window.innerHeight||document.documentElement.clientHeight||screen.height,i=u/window.screen.availWidth,l=(u-e)/2/i+n,m=(r-o)/2/i+c,p=window.open(t,s,"directories=no,toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width="+e/i+",height="+o/i+",top="+m+",left="+l);return window.focus&&p&&p.focus(),p}function B(t){if(t.indexOf("No data available")>=0){window.alert("No data available for this report.");return}window.open(t,"_blank","toolbar=no,scrollbars=yes,resizable=yes,width=800,height=600,top=0,left=0")}function P(t,s,e,o){v(t,{method:"POST",body:{query:s,variables:e||{}},onSuccess:function(n){o&&o(n.data||null,n.errors||void 0)},onError:function(n){o&&o(null,[{message:"GraphQL request failed with status "+n}])}})}function b(t){let s=t.dataset;return s&&s.key?s.key:null}function F(t,s){let e=s.attributes;for(let n=0;n<e.length;n++){let c=e[n];t.getAttribute(c.name)!==c.value&&t.setAttribute(c.name,c.value)}Array.prototype.slice.call(t.attributes).forEach(function(n){s.hasAttribute(n.name)||t.removeAttribute(n.name)})}function G(t,s){let e=s.tagName;e==="INPUT"||e==="TEXTAREA"||e==="SELECT"||(F(t,s),t.children.length||s.children.length?L(t,s):t.innerHTML!==s.innerHTML&&(t.innerHTML=s.innerHTML))}function L(t,s){let e=Array.prototype.slice.call(t.children),o=Array.prototype.slice.call(s.children),n={};e.forEach(function(r){let i=b(r);i&&(n[i]=r)});let c=[];for(let r=0;r<o.length;r++){let i=o[r],l=b(i),m=null;l&&n[l]?m=n[l]:!l&&e[r]&&!b(e[r])&&e[r].tagName===i.tagName&&(m=e[r]),m&&m.tagName===i.tagName?(G(m,i),reused.push(m),c.push(m)):c.push(i)}let u=t.firstElementChild;for(let r=0;r<c.length;r++){let i=c[r];i===u?u=u.nextElementSibling:t.insertBefore(i,u)}e.forEach(function(r){c.indexOf(r)===-1&&r.parentNode===t&&t.removeChild(r)}),reused}function R(t,s){let e=document.createElement("div");if(e.innerHTML=s,!e.children.length||!t.children.length){t.innerHTML=s;return}L(t,e)}function J(t){return/^wss?:\/\//.test(t)?t:(typeof location<"u"&&location.protocol==="https:"?"wss":"ws")+"://"+location.host+t}function N(t,s){return t&&typeof t=="object"?t.type==="live"?s&&t.name&&t.name!==s?null:t.html!=null?String(t.html):null:null:typeof t=="string"?t:null}function S(t){if(typeof document>"u")return;let e=(t||document).querySelectorAll("[data-frond-live]");Array.prototype.slice.call(e).forEach(function(o){if(o.__frondLive)return;o.__frondLive=!0;let n=o.getAttribute("data-mode"),c=o.getAttribute("data-frond-live");if(n==="poll"){let u=o.getAttribute("data-src"),r=(parseInt(o.getAttribute("data-interval"),10)||5)*1e3,i=setInterval(function(){typeof document<"u"&&document.hidden||v(u,{method:"GET",onSuccess:function(l){R(o,typeof l=="string"?l:String(l))}})},r);o.__frondLiveStop=function(){clearInterval(i)}}else if(n==="ws"){let u=M(J(o.getAttribute("data-ws")));u.on("message",function(r){let i=N(r,c);i!==null&&R(o,i)}),o.__frondLiveStop=function(){u.close()}}else n==="sse"&&typeof console<"u"&&console.warn&&console.warn("[frond.live] sse transport is not wired yet (v1 supports poll and ws); block '"+c+"' shows first paint only. Use poll or ws.")})}var C={request:v,load:_,post:k,inject:h,form:x,ws:M,sse:I,live:S,cookie:U,message:j,popup:X,report:B,graphql:P,get token(){return y},set token(t){y=t}};typeof window<"u"&&(window.frond=C,typeof document<"u"&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){S()}):S()));return W(z);})();
 /* Frond v2.2.0 - tina4.com */

package/packages/core/src/routeDiscovery.ts

@@ -64,8 +64,16 @@ export async function discoverRoutes(routesDir: string): Promise<RouteDefinition
 
       const meta: RouteMeta | undefined = mod.meta;
       const template: string | undefined = typeof mod.template === "string" ? mod.template : undefined;
-
-      definitions.push({ method, pattern, handler, filePath, meta, template });
+      // Auth opt-outs a route file can export (parity with the imperative
+      // `.noAuth()` / AutoCrud `secure: false`). A generated public write file
+      // (`generate route … --public`, or the always-public auth login/register)
+      // does `export const secure = false;`; without threading it here the
+      // router would keep its secure-by-default write gate and the opt-out
+      // would be inert. Only booleans are honoured — anything else is ignored.
+      const secure: boolean | undefined = typeof mod.secure === "boolean" ? mod.secure : undefined;
+      const noAuth: boolean | undefined = typeof mod.noAuth === "boolean" ? mod.noAuth : undefined;
+
+      definitions.push({ method, pattern, handler, filePath, meta, template, secure, noAuth });
       _seenFiles.add(filePath);
       _seenMtimes.set(filePath, currentMtime);
       registeredFromThisScan++;

package/packages/core/src/types.ts

@@ -109,7 +109,15 @@ export type Tina4Response =
   ((data?: unknown, statusCode?: number, contentType?: string) => Tina4Response)
   & Tina4ResponseMethods;
 
-export type RouteHandler = (req: Tina4Request, res: Tina4Response) => Promise<void> | void;
+// A route handler may resolve `void` (it wrote to `res` directly) OR return the
+// `Tina4Response` from `res.json(...)` / `response(...)` - the established
+// convention across the framework's own routes, realtime handlers, and the
+// `generate` scaffolding (`return res.json(...)`). The dispatcher tolerates a
+// returned response; the type just has to allow it.
+export type RouteHandler = (
+  req: Tina4Request,
+  res: Tina4Response,
+) => Tina4Response | void | Promise<Tina4Response | void>;
 
 export interface RouteDefinition {
   method: string;

package/packages/orm/src/baseModel.ts

@@ -586,6 +586,7 @@ export class BaseModel {
    * @param limit      Max records (default 20)
    * @param offset     Skip records (default 0)
    * @param include    Relationship names to eager-load
+   * @param orderBy    ORDER BY clause (e.g. "name ASC")
    */
   static async where<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
@@ -594,6 +595,7 @@ export class BaseModel {
     limit: number = 20,
     offset: number = 0,
     include?: string[],
+    orderBy?: string,
   ): Promise<T[]> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
@@ -607,7 +609,8 @@ export class BaseModel {
     }
     parts.push(`(${conditions})`);
 
-    const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")} LIMIT ${limit} OFFSET ${offset}`;
+    const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
+    const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")}${orderClause} LIMIT ${limit} OFFSET ${offset}`;
 
     const rows = await adapterQuery(db, sql, params);
     const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);