@assemora/data 0.1.0

package/dist/slow-queries.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Slow query logging (SPEC.md §88).
+ *
+ * The data layer owns the query, so it owns the timing. What it writes down is the
+ * *shape* of a query that took too long — which table, which operation, which columns
+ * were filtered on, which relations were loaded — and never one value the caller
+ * passed in.
+ *
+ * The logger arrives the way the adapter does, through a registration made once when
+ * the application boots (SPEC.md §33). A model declaration takes no logger, a query
+ * takes no logger, and nothing in the data layer's public API grew a parameter for
+ * something only the composition root can know.
+ */
+import { type Logger } from '@assemora/core';
+import type { QueryAst } from '@assemora/database';
+export type SlowQueryLogOptions = {
+    /**
+     * A query that takes at least this long is written down. 200ms.
+     *
+     * SPEC.md §89 budgets a whole REST read at 100ms and a whole mutation at 150ms, so a
+     * single statement above 200ms is already outside what the application promised —
+     * which is what makes this quiet in a healthy process and loud in a sick one. The
+     * threshold *is* the throttle: a line is only ever written for a query that was
+     * slow, and when that stops being rare, that is the thing worth knowing.
+     *
+     * `0` logs every query, which is occasionally what you want while looking at one
+     * endpoint and never what you want in production.
+     */
+    readonly slowerThanMs?: number;
+};
+/** Above the §89 budget for a whole request, so a healthy application writes nothing. */
+export declare const DEFAULT_SLOW_QUERY_MS = 200;
+/**
+ * Starts writing down the queries that take too long.
+ *
+ * ```ts
+ * useSlowQueryLog(app.logger)
+ * useSlowQueryLog(app.logger, { slowerThanMs: 50 })
+ * ```
+ *
+ * Registering is the switch, and `assemora()` registers it for every application it
+ * builds — so a project that says nothing still gets the log, and one built by hand
+ * with `createApplication()` opts in with this one line.
+ */
+export declare const useSlowQueryLog: (logger: Logger, options?: SlowQueryLogOptions) => void;
+export declare const clearSlowQueryLog: () => void;
+/**
+ * Notes that a query ran, and writes it down if it was slow.
+ *
+ * `answer` is what the adapter replied with, and it is absent when the query failed.
+ * Only an array is counted: a `count` replies with the number it was asked for, which
+ * is an answer rather than a row count, and this line carries no answers.
+ */
+export declare const recordQuery: (query: QueryAst, durationMs: number, answer?: unknown) => void;
+//# sourceMappingURL=slow-queries.d.ts.map

package/dist/slow-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slow-queries.d.ts","sourceRoot":"","sources":["../src/slow-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAsB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAChE,OAAO,KAAK,EAAa,QAAQ,EAAgB,MAAM,oBAAoB,CAAA;AAE3E,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAIxC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,WAAY,MAAM,YAAW,mBAAmB,KAAQ,IAYnF,CAAA;AAED,eAAO,MAAM,iBAAiB,QAAO,IAEpC,CAAA;AAuCD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,UAAW,QAAQ,cAAc,MAAM,WAAW,OAAO,KAAG,IAcnF,CAAA"}

package/dist/slow-queries.js

@@ -0,0 +1,96 @@
+/**
+ * Slow query logging (SPEC.md §88).
+ *
+ * The data layer owns the query, so it owns the timing. What it writes down is the
+ * *shape* of a query that took too long — which table, which operation, which columns
+ * were filtered on, which relations were loaded — and never one value the caller
+ * passed in.
+ *
+ * The logger arrives the way the adapter does, through a registration made once when
+ * the application boots (SPEC.md §33). A model declaration takes no logger, a query
+ * takes no logger, and nothing in the data layer's public API grew a parameter for
+ * something only the composition root can know.
+ */
+import { ConfigurationError } from '@assemora/core';
+/** Above the §89 budget for a whole request, so a healthy application writes nothing. */
+export const DEFAULT_SLOW_QUERY_MS = 200;
+let log;
+/**
+ * Starts writing down the queries that take too long.
+ *
+ * ```ts
+ * useSlowQueryLog(app.logger)
+ * useSlowQueryLog(app.logger, { slowerThanMs: 50 })
+ * ```
+ *
+ * Registering is the switch, and `assemora()` registers it for every application it
+ * builds — so a project that says nothing still gets the log, and one built by hand
+ * with `createApplication()` opts in with this one line.
+ */
+export const useSlowQueryLog = (logger, options = {}) => {
+    const slowerThanMs = options.slowerThanMs ?? DEFAULT_SLOW_QUERY_MS;
+    // A NaN threshold compares false against everything, so an unread environment
+    // variable would switch the log off in silence rather than fail where it was written.
+    if (!Number.isFinite(slowerThanMs) || slowerThanMs < 0) {
+        throw new ConfigurationError('A slow query threshold is a number of milliseconds that is not negative. Pass 0 to log every query.');
+    }
+    log = { logger, slowerThanMs };
+};
+export const clearSlowQueryLog = () => {
+    log = undefined;
+};
+/**
+ * What a condition was, with everything the caller passed taken out of it.
+ *
+ * A column name is schema. It is already in the OpenAPI document, in the generated SDK
+ * and in the MCP tool list, and knowing which columns a slow query filtered on is the
+ * whole difference between a line that names the missing index and a line that names
+ * only the table.
+ *
+ * A *value* is the caller's, and this is the one place in the framework where that
+ * distinction has teeth: a `where` carries whatever was handed to it — an email
+ * address, a session token digest, a password on its way to be compared — and a slow
+ * query log is exactly the file that gets attached to a ticket and pasted into a chat.
+ * So nothing that was passed in is written here. That includes a JSON path, which
+ * names a key inside a document that has no schema for it to belong to.
+ */
+const shapeOf = (conditions) => conditions.flatMap((condition) => {
+    if (condition.kind === 'group')
+        return shapeOf(condition.conditions);
+    if (condition.kind === 'json')
+        return [`${condition.field} json ${condition.operator}`];
+    return [`${condition.field} ${condition.operator}`];
+});
+/**
+ * The relation paths the query loaded, as the caller wrote them.
+ *
+ * Here because SPEC.md §89 asks for N+1 queries to be caught by logs as well as by
+ * tests, and the same relation appearing under one model over and over is what that
+ * looks like from the outside.
+ */
+const pathsOf = (loads, prefix = '') => loads.flatMap((load) => {
+    const path = `${prefix}${load.relation}`;
+    return load.nested.length === 0 ? [path] : pathsOf(load.nested, `${path}.`);
+});
+/**
+ * Notes that a query ran, and writes it down if it was slow.
+ *
+ * `answer` is what the adapter replied with, and it is absent when the query failed.
+ * Only an array is counted: a `count` replies with the number it was asked for, which
+ * is an answer rather than a row count, and this line carries no answers.
+ */
+export const recordQuery = (query, durationMs, answer) => {
+    if (log === undefined || durationMs < log.slowerThanMs)
+        return;
+    const filters = shapeOf(query.where);
+    const relations = pathsOf(query.with);
+    log.logger.warn('A query was slower than the threshold', {
+        model: query.model,
+        operation: query.operation,
+        durationMs,
+        ...(Array.isArray(answer) ? { rows: answer.length } : {}),
+        ...(filters.length === 0 ? {} : { filters }),
+        ...(relations.length === 0 ? {} : { relations }),
+    });
+};
+//# sourceMappingURL=slow-queries.js.map

package/dist/slow-queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slow-queries.js","sourceRoot":"","sources":["../src/slow-queries.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@assemora/data",
+  "version": "0.1.0",
+  "description": "Assemora Data: model(), query builder, relations, scopes, Query AST",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assemora/assemora.git",
+    "directory": "packages/data"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@assemora/schema": "0.1.0",
+    "@assemora/core": "0.1.0",
+    "@assemora/database": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}