@mauroandre/velojs 0.0.57 → 0.0.59

package/dist/telemetry-node.js

@@ -0,0 +1,93 @@
+import i from "node:fs";
+import d from "node:os";
+import c from "node:path";
+import { parseDotEnv as m, initTelemetry as w, byteLength as h } from "./telemetry.js";
+function $(t = process.cwd()) {
+  try {
+    return m(i.readFileSync(c.join(t, ".env"), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function v() {
+  const t = d.hostname().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return t ? `${process.pid}-${t}` : String(process.pid);
+}
+function S(t = process.cwd()) {
+  try {
+    const e = i.readFileSync(c.join(t, "package.json"), "utf-8"), o = JSON.parse(e);
+    return typeof o.version == "string" ? o.version : null;
+  } catch {
+    return null;
+  }
+}
+function j(t) {
+  try {
+    return i.statSync(t).size;
+  } catch {
+    return 0;
+  }
+}
+async function k(t) {
+  const e = t.file, o = t.sink;
+  let s = null, a = 0, l = 0;
+  const p = async () => {
+    s || !e || (await i.promises.mkdir(c.dirname(e), { recursive: !0 }), a = j(e), s = await i.promises.open(e, "a"));
+  }, f = async () => {
+    if (!e) return;
+    s && (await s.close().catch(() => {
+    }), s = null);
+    let r = l + 1;
+    for (; i.existsSync(`${e}.${r}`); ) r += 1;
+    await i.promises.rename(e, `${e}.${r}`), l = r, a = 0, s = await i.promises.open(e, "a");
+  }, y = async (r) => {
+    if (e)
+      try {
+        await p();
+        const n = h(r) + 1;
+        a > 0 && a + n > t.maxBytes && await f(), await s.write(`${r}
+`), a += n;
+      } catch (n) {
+        console.error(`[velojs] telemetry file destination failed (${e}):`, n);
+      }
+  }, u = async (r) => {
+    if (o)
+      try {
+        const n = await fetch(o, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: r
+        });
+        await n.text().catch(() => ""), n.ok || console.error(`[velojs] telemetry sink responded ${n.status} (${o})`);
+      } catch (n) {
+        console.error(`[velojs] telemetry sink destination failed (${o}):`, n);
+      }
+  };
+  return {
+    file: e,
+    sink: o,
+    async write(r) {
+      const n = [];
+      e && n.push(y(r)), o && n.push(u(r)), await Promise.allSettled(n);
+    },
+    async close() {
+      s && (await s.close().catch(() => {
+      }), s = null);
+    }
+  };
+}
+async function z(t) {
+  await w({
+    writer: k,
+    instanceLabel: t?.instanceLabel ?? v(),
+    version: S(),
+    fileEnv: $(process.cwd())
+  });
+}
+export {
+  z as initNodeTelemetry,
+  v as nodeInstanceLabel,
+  k as nodeTelemetryWriter,
+  S as readAppVersion,
+  $ as readProjectEnv
+};

package/dist/telemetry.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Native telemetry — boundary traces, first-class JSONL (client-safe core).
+ *
+ * The framework owns a finite set of bottlenecks (page SSR, `?_data=1` refetch,
+ * action, declarative endpoint, stream connect, socket setup, channel connect)
+ * plus the emit chain that runs outside any request. This module turns each of
+ * them into one JSONL event with duration, status, response bytes, child spans
+ * and — on long connections — one delivery line per frame delivered and a final
+ * close line. The file is the production artifact; `velojs telemetry` ranks it.
+ *
+ * Activation is by destination, never by a flag: `VELO_TELEMETRY_FILE` and/or
+ * `VELO_TELEMETRY_SINK_URL` present and non-empty turn collection on; none of
+ * them (absent or empty) leaves the whole module inert — no file, no event, no
+ * cost — in any environment, dev included. The values expand `~` and `$VAR`,
+ * the effective file carries an instance suffix (pid/hostname) so replicas
+ * sharing a volume never corrupt each other, and `VELO_TELEMETRY_MAX_MB`
+ * (default 10) is the only pruning mechanism: size-based rotation.
+ *
+ * This core is import-safe on the client (no Node builtin anywhere): it holds
+ * the event model, the trace API and the destination resolution. The writer
+ * that touches the filesystem and the network lives in `telemetry-node.ts`,
+ * injected at boot — the client bundle never reaches it.
+ */
+/** Every line of the JSONL carries one of these types. */
+export type TelemetryEventType = "boot" | "page" | "data" | "action" | "endpoint" | "stream-connect" | "socket-connect" | "channel-connect" | "emit" | "delivery" | "close";
+export type TelemetryStatus = "ok" | "error";
+/** One child span: name, start relative to the trace, own duration and status. */
+export interface TelemetrySpan {
+    name: string;
+    /** Milliseconds since the trace started. */
+    start: number;
+    duration: number;
+    status: TelemetryStatus;
+}
+/** The open field set shared by the trace handle and every emitted line. */
+export interface TelemetryEventFields {
+    status?: TelemetryStatus | undefined;
+    duration?: number | undefined;
+    bytes?: number | undefined;
+    route?: string | undefined;
+    module?: string | undefined;
+    name?: string | undefined;
+    method?: string | undefined;
+    channel?: string | undefined;
+    partition?: string | null | undefined;
+    mode?: "invalidate" | "slice" | undefined;
+    connections?: number | undefined;
+}
+/** One JSONL line. Optional fields exist only when the type has them. */
+export interface TelemetryEvent extends TelemetryEventFields {
+    trace: string;
+    ts: string;
+    type: TelemetryEventType;
+    /** Cumulative ordinal on `delivery` lines; total on `close` lines. */
+    deliveries?: number | undefined;
+    spans?: TelemetrySpan[] | undefined;
+    version?: string | null | undefined;
+    env?: string | null | undefined;
+    file?: string | null | undefined;
+    sink?: string | null | undefined;
+    maxMb?: number | undefined;
+}
+export interface TelemetrySpanHandle {
+    /** Closes the span; first call wins. */
+    end(status?: TelemetryStatus): void;
+}
+/** A span collector detached from any trace — used for coalesced emit rounds. */
+export interface TelemetrySpanRecorder {
+    readonly spans: TelemetrySpan[];
+    span(name: string): TelemetrySpanHandle;
+}
+/**
+ * One open trace. `end()` writes the main line once; `delivery()` and
+ * `close()` write the light lines of a long connection, all carrying the same
+ * trace id. A disabled trace is a shared no-op.
+ */
+export interface TelemetryTrace extends TelemetrySpanRecorder {
+    readonly id: string;
+    readonly enabled: boolean;
+    addSpans(spans: readonly TelemetrySpan[]): void;
+    setFields(fields: TelemetryEventFields): void;
+    end(fields?: TelemetryEventFields): void;
+    delivery(bytes?: number): void;
+    close(fields?: TelemetryEventFields): void;
+}
+/** The destination model: env values resolved, defaults applied. */
+export interface TelemetrySettings {
+    /** `VELO_TELEMETRY_FILE` expanded (instance suffix NOT applied), or null. */
+    file: string | null;
+    /** `VELO_TELEMETRY_SINK_URL` expanded, or null. */
+    sink: string | null;
+    /** `VELO_TELEMETRY_MAX_MB`, default 10. */
+    maxMb: number;
+}
+/** Read-only view of the runtime state — the disabled-mode assertion. */
+export interface TelemetryState {
+    enabled: boolean;
+    file: string | null;
+    sink: string | null;
+    maxMb: number;
+    /** Events handed to the destinations since the last reset. */
+    events: number;
+}
+/**
+ * Where the events go. The core never touches the filesystem: the Node adapter
+ * (`telemetry-node.ts`) implements this and is injected at boot.
+ */
+export interface TelemetryWriter {
+    /** Effective file path the writer appends to (instance suffix applied). */
+    readonly file: string | null;
+    /** Sink URL the writer POSTs to. */
+    readonly sink: string | null;
+    write(line: string): Promise<void>;
+    close(): Promise<void>;
+}
+/** What the writer factory needs to build a destination writer. */
+export interface TelemetryWriterInput {
+    /** Effective file path (instance suffix applied) or null. */
+    file: string | null;
+    sink: string | null;
+    maxBytes: number;
+}
+export interface TelemetryInitOptions {
+    /** Builds the destination writer (the Node adapter, injected). */
+    writer: (input: TelemetryWriterInput) => Promise<TelemetryWriter>;
+    /** Overrides the pid/hostname suffix (tests only). */
+    instanceLabel?: string | undefined;
+    /** The app version served — goes into the boot record. */
+    version?: string | null | undefined;
+    /**
+     * The project's `.env` values, the fallback for the destination keys — the
+     * Node adapter reads them; the process environment always wins.
+     */
+    fileEnv?: Record<string, string> | undefined;
+}
+/** The default rotation limit, in MB. */
+export declare const DEFAULT_MAX_MB = 10;
+/**
+ * Expands `~` (home) and `$VAR` / `${VAR}` in a destination value, against the
+ * merged environment (process env wins over `.env`). An undefined reference is
+ * kept literally — a silently wrong path is worse than a visible one, and the
+ * boot record shows the effective destination for diagnosis.
+ */
+export declare function expandTelemetryValue(value: string, env: Record<string, string | undefined>): string;
+/**
+ * Parses a `.env` file body. Deliberately a small subset — `KEY=value` (with
+ * optional `export`), double/single quotes, `#` comments and inline comments
+ * after whitespace — which is all the framework consumes: the telemetry keys
+ * of the project, and nothing else.
+ */
+export declare function parseDotEnv(content: string): Record<string, string>;
+/**
+ * Resolves the destination model from the environment. `process env` values
+ * win over the project's `.env` (the same precedence the release script uses);
+ * a key present but empty counts as unset-at-that-level. Returns `null` when
+ * neither destination is configured — the whole collection is off.
+ */
+export declare function resolveTelemetrySettings(env: Record<string, string | undefined>, fileEnv?: Record<string, string>): TelemetrySettings | null;
+/**
+ * The effective file of one instance: the instance suffix goes before the
+ * extension, so several processes pointing the same destination write
+ * different files and an append never interleaves with another process's.
+ */
+export declare function effectiveTelemetryFile(baseFile: string, instance: string): string;
+/**
+ * Starts the collection for this process: resolves the destination from the
+ * environment and writes the boot record — the first event of every active
+ * destination, the file's first line and the sink's first POST. Without a
+ * destination this is a no-op; with one it runs once per process (idempotent).
+ *
+ * The writer comes from the caller: `initNodeTelemetry()` (the Node adapter)
+ * is what the server boot uses.
+ */
+export declare function initTelemetry(options: TelemetryInitOptions): Promise<void>;
+/** Waits until every queued event reached its destinations. */
+export declare function flushTelemetry(): Promise<void>;
+/** Whether a destination is active in this process. */
+export declare function isTelemetryEnabled(): boolean;
+/** Read-only snapshot of the runtime state. */
+export declare function telemetryState(): TelemetryState;
+/**
+ * Test-only. Closes the writer and drops the runtime, so the next
+ * `initTelemetry()` re-reads the environment from scratch.
+ */
+export declare function __resetTelemetry(): Promise<void>;
+/** Milliseconds of a string as UTF-8, without pulling Buffer into the client. */
+export declare function byteLength(value: string): number;
+/** The JSON byte size of a value, when it serializes at all. */
+export declare function jsonBytes(value: unknown): number | undefined;
+/** A detached span collector (the coalesced emit round fills it). */
+export declare function spanRecorder(): TelemetrySpanRecorder;
+/**
+ * Opens one trace. Every finished line carries the trace id and its own
+ * timestamp; the fields given here (route, module, channel, …) travel on the
+ * main line and on the delivery/close lines of the same trace.
+ */
+export declare function trace(type: TelemetryEventType, fields?: TelemetryEventFields, startedAt?: number): TelemetryTrace;
+/**
+ * The size of a response body, when it has one that can be measured without
+ * disturbing it: declared `content-length` wins; a stream (chunked transfer or
+ * an event stream) has no body size — the delivery lines of a long connection
+ * account for its frames instead.
+ */
+export declare function responseBytes(response: Response): Promise<number | undefined>;

package/dist/telemetry.js

@@ -0,0 +1,240 @@
+const R = 10;
+function _(e, i) {
+  let n = e;
+  return n === "~" ? n = w(i) : n.startsWith("~/") && (n = `${w(i)}${n.slice(1)}`), n.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (s, r, o) => {
+    const l = i[r ?? o];
+    return l === void 0 ? s : l;
+  });
+}
+function w(e) {
+  return (e.HOME ?? e.USERPROFILE ?? "").replace(/\/+$/, "");
+}
+function D(e) {
+  const i = {};
+  for (const n of e.split(/\r?\n/)) {
+    const s = n.trim();
+    if (!s || s.startsWith("#")) continue;
+    const r = s.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!r) continue;
+    const o = r[1];
+    let t = r[2].trim();
+    if (t.length >= 2 && t.startsWith('"') && t.endsWith('"'))
+      t = t.slice(1, -1).replace(/\\n/g, `
+`).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    else if (t.length >= 2 && t.startsWith("'") && t.endsWith("'"))
+      t = t.slice(1, -1);
+    else {
+      const l = t.indexOf(" #");
+      l !== -1 && (t = t.slice(0, l).trim());
+    }
+    i[o] = t;
+  }
+  return i;
+}
+function S(e, i = {}) {
+  const n = (d) => {
+    const c = e[d];
+    return c !== void 0 ? c.trim() : (i[d] ?? "").trim();
+  }, s = n("VELO_TELEMETRY_FILE"), r = n("VELO_TELEMETRY_SINK_URL");
+  if (!s && !r) return null;
+  const o = { ...i, ...e }, t = n("VELO_TELEMETRY_MAX_MB"), l = Number(t), h = Number.isFinite(l) && l > 0 ? l : 10;
+  return {
+    file: s ? _(s, o) : null,
+    sink: r ? _(r, o) : null,
+    maxMb: h
+  };
+}
+function $(e, i) {
+  const n = Math.max(e.lastIndexOf("/"), e.lastIndexOf("\\")), s = n === -1 ? "" : e.slice(0, n + 1), r = n === -1 ? e : e.slice(n + 1), o = r.lastIndexOf("."), t = o > 0 ? `${r.slice(0, o)}.${i}${r.slice(o)}` : `${r}.${i}`;
+  return `${s}${t}`;
+}
+let u = null, E = !1, f = null, M = 0;
+function x() {
+  return M += 1, `${Date.now().toString(36)}-${M.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function p(e, i) {
+  for (const [n, s] of Object.entries(i))
+    s !== void 0 && (e[n] = s);
+  return e;
+}
+const y = (e) => Math.round(e * 100) / 100, v = () => typeof performance < "u" ? performance.now() : Date.now(), b = () => (/* @__PURE__ */ new Date()).toISOString();
+function L() {
+  return typeof process < "u" ? process.env : {};
+}
+async function B(e) {
+  if (!E) {
+    if (f) {
+      await f;
+      return;
+    }
+    f = (async () => {
+      const i = L(), n = S(i, e.fileEnv ?? {});
+      if (!n) return;
+      const s = e.instanceLabel ?? `pid-${String(globalThis.process?.pid ?? "0")}`, r = n.file ? $(n.file, s) : null, o = await e.writer({
+        file: r,
+        sink: n.sink,
+        maxBytes: n.maxMb * 1024 * 1024
+      }), t = {
+        settings: n,
+        writer: o,
+        file: o.file ?? r,
+        sink: o.sink ?? n.sink,
+        version: e.version ?? null,
+        env: i.NODE_ENV ?? null,
+        chain: Promise.resolve(),
+        events: 0
+      };
+      u = t, E = !0;
+      const l = { trace: x(), ts: b(), type: "boot" };
+      p(l, {
+        version: t.version,
+        env: t.env,
+        file: t.file,
+        sink: t.sink,
+        maxMb: t.settings.maxMb
+      }), await m(t, l);
+    })(), await f, f = null;
+  }
+}
+function m(e, i) {
+  return e.events += 1, e.chain = e.chain.then(() => e.writer.write(JSON.stringify(i))).catch(() => {
+  }), e.chain;
+}
+async function F() {
+  await u?.chain;
+}
+function I() {
+  return u !== null;
+}
+function z() {
+  return {
+    enabled: u !== null,
+    file: u?.file ?? null,
+    sink: u?.sink ?? null,
+    maxMb: u?.settings.maxMb ?? 10,
+    events: u?.events ?? 0
+  };
+}
+async function P() {
+  f && await f;
+  const e = u;
+  u = null, E = !1, f = null, e && (await e.chain.catch(() => {
+  }), await e.writer.close().catch(() => {
+  }));
+}
+const T = { end: () => {
+} };
+function O(e) {
+  return typeof Buffer < "u" ? Buffer.byteLength(e) : new TextEncoder().encode(e).length;
+}
+function W(e) {
+  try {
+    const i = JSON.stringify(e);
+    return i === void 0 ? void 0 : O(i);
+  } catch {
+    return;
+  }
+}
+function k(e, i, n) {
+  const s = v();
+  let r = !1;
+  return {
+    end(o = "ok") {
+      r || (r = !0, e.push({
+        name: n,
+        start: y(s - i),
+        duration: y(v() - s),
+        status: o
+      }));
+    }
+  };
+}
+const N = {
+  id: "",
+  enabled: !1,
+  spans: [],
+  span: () => T,
+  addSpans: () => {
+  },
+  setFields: () => {
+  },
+  end: () => {
+  },
+  delivery: () => {
+  },
+  close: () => {
+  }
+}, A = {
+  spans: [],
+  span: () => T
+};
+function Z() {
+  if (!u) return A;
+  const e = [];
+  return { spans: e, span: (i) => k(e, v(), i) };
+}
+function U(e, i = {}, n = v()) {
+  const s = u;
+  if (!s) return N;
+  const r = x(), o = { ...i }, t = [];
+  let l = !1, h = 0;
+  const d = (c, a) => {
+    const g = { trace: r, ts: b(), type: c };
+    return p(g, o), p(g, a), g;
+  };
+  return {
+    id: r,
+    enabled: !0,
+    spans: t,
+    span: (c) => k(t, n, c),
+    addSpans(c) {
+      for (const a of c) t.push(a);
+    },
+    setFields(c) {
+      p(o, c);
+    },
+    end(c = {}) {
+      if (l) return;
+      l = !0;
+      const a = d(e, c);
+      a.status === void 0 && (a.status = "ok"), a.duration === void 0 && (a.duration = y(v() - n)), t.length > 0 && (a.spans = [...t]), m(s, a);
+    },
+    delivery(c) {
+      h += 1, m(s, d("delivery", { deliveries: h, ...c === void 0 ? {} : { bytes: c } }));
+    },
+    close(c = {}) {
+      const a = d("close", c);
+      a.deliveries = h, a.status === void 0 && (a.status = "ok"), a.duration === void 0 && (a.duration = y(v() - n)), m(s, a);
+    }
+  };
+}
+async function V(e) {
+  if (!e.body || (e.headers.get("content-type") ?? "").startsWith("text/event-stream") || (e.headers.get("transfer-encoding") ?? "").includes("chunked")) return;
+  const n = e.headers.get("content-length");
+  if (n !== null) {
+    const s = Number(n);
+    if (Number.isFinite(s) && s >= 0) return s;
+  }
+  try {
+    return O(await e.clone().text());
+  } catch {
+    return;
+  }
+}
+export {
+  R as DEFAULT_MAX_MB,
+  P as __resetTelemetry,
+  O as byteLength,
+  $ as effectiveTelemetryFile,
+  _ as expandTelemetryValue,
+  F as flushTelemetry,
+  B as initTelemetry,
+  I as isTelemetryEnabled,
+  W as jsonBytes,
+  D as parseDotEnv,
+  S as resolveTelemetrySettings,
+  V as responseBytes,
+  Z as spanRecorder,
+  z as telemetryState,
+  U as trace
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mauroandre/velojs",
-    "version": "0.0.57",
+    "version": "0.0.59",
     "type": "module",
     "description": "Fullstack web framework built on Hono + Preact with Vite-powered AST transforms",
     "keywords": [