@mistriwork/engine 1.0.0-rc.75 → 1.0.0-rc.77

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -54,6 +54,28 @@ export declare const pipelinesAs: (wrapper: PgQuery, client: PgQuery) => void;
54
54
  /** The database browser's reader pool size unless a connection or the command line says otherwise.
55
55
  * An App's is balanced against its writers (appReaders). */
56
56
  export declare const DEFAULT_READERS = 4;
57
+ /** The longest an idle connection may be kept: a day. Past it a forgotten setting holds a server backend for nothing,
58
+ * and a hosted database or pooler has closed the socket long before. */
59
+ export declare const MAX_IDLE_SECONDS = 86400;
60
+ /** Whether `value` is an idle window a connection accepts: whole seconds from 1 to a day. */
61
+ export declare function isIdleSeconds(value: unknown): value is number;
62
+ /** Whether `value` is a warm-connection count a connection accepts: a whole number from 0 to the pool's largest size. */
63
+ export declare function isMinIdle(value: unknown): value is number;
64
+ /**
65
+ * How long an idle connection stays open and how many stay connected through it, for one pool: the connection's own
66
+ * `pool` setting, else the server's (`MISTRI_POOL_IDLE`, in seconds), else the built-in five minutes and `warm`. The
67
+ * connection's wins, as `pool.read` wins over `--read-pool`: the deployment sets a default, one database overrides it.
68
+ * `minIdle` is capped at the pool's size, which pg would otherwise refuse.
69
+ */
70
+ export declare function resolvePoolIdle(options: {
71
+ readonly idleSeconds?: number;
72
+ readonly minIdle?: number;
73
+ }, server: {
74
+ readonly idleSeconds?: number;
75
+ }, warm: number, size: number): {
76
+ idleTimeoutMillis: number;
77
+ min: number;
78
+ };
57
79
  /** The most readers one database's pool may hold. Past this, a pooler in front of the server is the tool. */
58
80
  export declare const MAX_READERS = 64;
59
81
  /** Whether `value` is a reader pool size a manager accepts: a whole number from 1 to 64. */
@@ -63,6 +85,10 @@ export interface PgConnectionOptions {
63
85
  readonly readers?: number;
64
86
  /** Writer connections held at once, 1–64, where writes are keyed (writeLanes.ts); one where they are serial. */
65
87
  readonly writers?: number;
88
+ /** Seconds an idle connection stays open, 1 to 86400. The process's (`MISTRI_POOL_IDLE`), else five minutes, when absent. */
89
+ readonly idleSeconds?: number;
90
+ /** Connections each pool keeps open through an idle spell, 0 to 64 (never more than the pool's size). Two readers and one writer when absent. */
91
+ readonly minIdle?: number;
66
92
  /** How long a writer waits for a lock. The process's (`--lock-timeout`) when absent. */
67
93
  readonly lockTimeoutMs?: number;
68
94
  /** What sits between this process and the server. The process default when absent. */
@@ -113,6 +139,7 @@ export declare function appReaders(writers: number, cores?: number): number;
113
139
  export declare function configurePostgresPools(options: {
114
140
  readers?: number;
115
141
  pooler?: PoolerMode;
142
+ idleSeconds?: number;
116
143
  }): void;
117
144
  /** The defaults, as this server's settings leave them. */
118
145
  export declare function postgresPoolDefaults(): Readonly<{
@@ -156,6 +183,7 @@ export declare class PgConnectionManager {
156
183
  /** Bounded concurrency for best-effort pg_cancel_backend helper connections. */
157
184
  private cancelsInFlight;
158
185
  private readonly cancelQueue;
186
+ private readonly idle;
159
187
  private readonly pendingCancels;
160
188
  constructor(connectionString: string, onLoad?: (pg: unknown) => void, load?: PgPoolLoader, options?: PgConnectionOptions);
161
189
  /**
@@ -76,6 +76,30 @@ const WARM_WRITERS = 1;
76
76
  /** How long an idle connection stays open: five minutes, past a lunch-hour lull but well inside what a
77
77
  * hosted database or its pooler lets a connection sit. The extra ones (beyond the warm minimum) close then. */
78
78
  const IDLE_TIMEOUT_MS = 300_000;
79
+ /** The longest an idle connection may be kept: a day. Past it a forgotten setting holds a server backend for nothing,
80
+ * and a hosted database or pooler has closed the socket long before. */
81
+ export const MAX_IDLE_SECONDS = 86_400;
82
+ /** Whether `value` is an idle window a connection accepts: whole seconds from 1 to a day. */
83
+ export function isIdleSeconds(value) {
84
+ return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_IDLE_SECONDS;
85
+ }
86
+ /** Whether `value` is a warm-connection count a connection accepts: a whole number from 0 to the pool's largest size. */
87
+ export function isMinIdle(value) {
88
+ return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_READERS;
89
+ }
90
+ /**
91
+ * How long an idle connection stays open and how many stay connected through it, for one pool: the connection's own
92
+ * `pool` setting, else the server's (`MISTRI_POOL_IDLE`, in seconds), else the built-in five minutes and `warm`. The
93
+ * connection's wins, as `pool.read` wins over `--read-pool`: the deployment sets a default, one database overrides it.
94
+ * `minIdle` is capped at the pool's size, which pg would otherwise refuse.
95
+ */
96
+ export function resolvePoolIdle(options, server, warm, size) {
97
+ const seconds = options.idleSeconds ?? server.idleSeconds;
98
+ return {
99
+ idleTimeoutMillis: seconds === undefined ? IDLE_TIMEOUT_MS : seconds * 1000,
100
+ min: Math.min(options.minIdle ?? warm, size),
101
+ };
102
+ }
79
103
  /** The most readers one database's pool may hold. Past this, a pooler in front of the server is the tool. */
80
104
  export const MAX_READERS = 64;
81
105
  /** What pg-pool says when no connection came free within the acquisition timeout. */
@@ -126,7 +150,9 @@ export function configurePostgresPools(options) {
126
150
  const pooler = options.pooler ?? 'session';
127
151
  if (pooler !== 'session' && pooler !== 'transaction')
128
152
  throw new RangeError('The pooler is "session" or "transaction".');
129
- configureServerSettings({ readers, pooler });
153
+ if (options.idleSeconds !== undefined && !isIdleSeconds(options.idleSeconds))
154
+ throw new RangeError(`A PostgreSQL idle connection stays 1 to ${MAX_IDLE_SECONDS} seconds; ${String(options.idleSeconds)} is not one of them.`);
155
+ configureServerSettings({ readers, pooler, idleSeconds: options.idleSeconds });
130
156
  }
131
157
  /** The defaults, as this server's settings leave them. */
132
158
  export function postgresPoolDefaults() {
@@ -175,6 +201,7 @@ export class PgConnectionManager {
175
201
  /** Bounded concurrency for best-effort pg_cancel_backend helper connections. */
176
202
  cancelsInFlight = 0;
177
203
  cancelQueue = [];
204
+ idle;
178
205
  pendingCancels = new Set();
179
206
  constructor(connectionString, onLoad = () => { }, load = loadPg, options = {}) {
180
207
  this.connectionString = connectionString;
@@ -189,6 +216,11 @@ export class PgConnectionManager {
189
216
  if (!isWriterCount(writers))
190
217
  throw new RangeError(`A PostgreSQL write pool holds 1 to ${MAX_WRITERS} connections; ${String(writers)} is not one of them.`);
191
218
  this.pooler = options.pooler ?? serverSettings().pooler;
219
+ if (options.idleSeconds !== undefined && !isIdleSeconds(options.idleSeconds))
220
+ throw new RangeError(`A PostgreSQL idle connection stays 1 to ${MAX_IDLE_SECONDS} seconds; ${String(options.idleSeconds)} is not one of them.`);
221
+ if (options.minIdle !== undefined && !isMinIdle(options.minIdle))
222
+ throw new RangeError(`A PostgreSQL pool keeps 0 to ${MAX_READERS} idle connections; ${String(options.minIdle)} is not one of them.`);
223
+ this.idle = { idleSeconds: options.idleSeconds, minIdle: options.minIdle };
192
224
  this.network = options.network;
193
225
  this.pipelineReads = options.pipelineReads === true;
194
226
  this.timingLabel = options.timingLabel ?? 'app';
@@ -353,18 +385,19 @@ export class PgConnectionManager {
353
385
  throw new Error('Could not find a Pool export in the "pg" package.');
354
386
  const write = role !== 'read';
355
387
  const session = this.pooler === 'session';
388
+ const idle = resolvePoolIdle(this.idle, serverSettings(), role === 'read' ? WARM_READERS : WARM_WRITERS, this.meters[role].size);
356
389
  const pool = new Pool({
357
390
  ...this.dialOptions(),
358
391
  max: this.meters[role].size,
359
392
  connectionTimeoutMillis: 10_000,
360
- idleTimeoutMillis: IDLE_TIMEOUT_MS,
393
+ idleTimeoutMillis: idle.idleTimeoutMillis,
361
394
  /* Readers and the foreground writers keep a few connections warm
362
395
  (the background writer, which runs jobs that are not waited on, keeps none). The
363
396
  idle ones never keep the process alive by themselves, so a one-shot
364
397
  mode that forgets to close still exits: that is why the writer
365
398
  sets this too, now that it holds a connection through idle. */
366
399
  allowExitOnIdle: true,
367
- ...(role === 'background' ? {} : { min: Math.min(role === 'read' ? WARM_READERS : WARM_WRITERS, this.meters[role].size) }),
400
+ ...(role === 'background' ? {} : { min: idle.min }),
368
401
  /* A writer sends each statement as it is asked, not after the one
369
402
  before it is answered: a transaction that asks several at once
370
403
  (pipelined, postgresTransactionHandle.ts) pays one round trip for
@@ -23,6 +23,8 @@ export interface ServerSettings {
23
23
  readonly pooler: PoolerMode;
24
24
  /** `--write-pool`; unset, the balanced size (writeLanes.ts). */
25
25
  readonly writers?: number;
26
+ /** `MISTRI_POOL_IDLE`: seconds an idle PostgreSQL connection stays open; unset, five minutes (postgresPool.ts). */
27
+ readonly idleSeconds?: number;
26
28
  /** `--lock-timeout`; unset, the default. */
27
29
  readonly lockTimeoutMs?: number;
28
30
  /**
@@ -176,9 +176,10 @@ export declare function shutdownTimings(opts: Pick<Options, 'drainDelay' | 'shut
176
176
  * they cannot be used. Refused rather than clamped: a pod sized for 16
177
177
  * readers that quietly got 4 is a capacity plan nobody can see failing.
178
178
  */
179
- export declare function postgresPoolFlags(opts: Pick<Options, 'readPool' | 'writePool' | 'pooler' | 'lockTimeout'>): {
179
+ export declare function postgresPoolFlags(opts: Pick<Options, 'readPool' | 'writePool' | 'pooler' | 'lockTimeout'>, env?: NodeJS.ProcessEnv): {
180
180
  readers?: number;
181
181
  writers?: number;
182
182
  pooler?: PoolerMode;
183
183
  lockTimeoutMs?: number;
184
+ idleSeconds?: number;
184
185
  } | string;
@@ -5,7 +5,7 @@
5
5
  * test/prose.test.ts holds the two and the README to each other.
6
6
  */
7
7
  import { parseHostList } from '../http/trust.js';
8
- import { isReaderCount, MAX_READERS } from '../../adapters/postgresPool.js';
8
+ import { isIdleSeconds, isReaderCount, MAX_IDLE_SECONDS, MAX_READERS } from '../../adapters/postgresPool.js';
9
9
  import { isLockTimeout, isWriterCount, MAX_LOCK_TIMEOUT_MS, MAX_WRITERS, MIN_LOCK_TIMEOUT_MS } from '../../adapters/writeLanes.js';
10
10
  import { envName, productEnv } from '../product.js';
11
11
  /**
@@ -315,7 +315,7 @@ export function shutdownTimings(opts) {
315
315
  * they cannot be used. Refused rather than clamped: a pod sized for 16
316
316
  * readers that quietly got 4 is a capacity plan nobody can see failing.
317
317
  */
318
- export function postgresPoolFlags(opts) {
318
+ export function postgresPoolFlags(opts, env = process.env) {
319
319
  let readers;
320
320
  if (opts.readPool !== undefined) {
321
321
  readers = /^\d+$/.test(opts.readPool) ? Number(opts.readPool) : Number.NaN;
@@ -341,10 +341,21 @@ export function postgresPoolFlags(opts) {
341
341
  if (pooler !== undefined && pooler !== 'session' && pooler !== 'transaction') {
342
342
  return `--pooler takes "session" or "transaction"; "${pooler}" is neither. It comes from the flag or ${envName('POOLER')}.`;
343
343
  }
344
+ /* Environment only, like the deployment fact it is: how long a hosted database or its pooler lets a connection sit
345
+ idle. A connection's own "pool": { "idleSeconds" } wins over it (postgresPool.ts resolvePoolIdle). */
346
+ let idleSeconds;
347
+ const idle = productEnv('POOL_IDLE', env)?.trim();
348
+ if (idle) {
349
+ idleSeconds = /^\d+$/.test(idle) ? Number(idle) : Number.NaN;
350
+ if (!isIdleSeconds(idleSeconds)) {
351
+ return `${envName('POOL_IDLE')} takes whole seconds from 1 to ${MAX_IDLE_SECONDS}; "${idle}" is not one.`;
352
+ }
353
+ }
344
354
  return {
345
355
  ...(readers !== undefined ? { readers } : {}),
346
356
  ...(writers !== undefined ? { writers } : {}),
347
357
  ...(pooler !== undefined ? { pooler } : {}),
348
358
  ...(lockTimeoutMs !== undefined ? { lockTimeoutMs } : {}),
359
+ ...(idleSeconds !== undefined ? { idleSeconds } : {}),
349
360
  };
350
361
  }
@@ -301,7 +301,7 @@ interface ConfigFile {
301
301
  rows?: boolean;
302
302
  /** Table → columns never served over the connection (hiddenColumns.ts). */
303
303
  hidden?: HiddenColumnRules;
304
- /** `{ "read": n, "write": m }`: a PostgreSQL connection's pool sizes, checked by poolOf. */
304
+ /** `{ "read": n, "write": m, "idleSeconds": s, "minIdle": k }`: a PostgreSQL connection's pool sizes and idle window, checked by poolOf. */
305
305
  pool?: unknown;
306
306
  /** Read replicas' URLs, checked by replicasOf. */
307
307
  replicas?: unknown;
@@ -478,6 +478,8 @@ export class Registry {
478
478
  postgres: {
479
479
  ...(entry.config.pool.read !== undefined ? { readers: entry.config.pool.read } : {}),
480
480
  ...(entry.config.pool.write !== undefined ? { writers: entry.config.pool.write } : {}),
481
+ ...(entry.config.pool.idleSeconds !== undefined ? { idleSeconds: entry.config.pool.idleSeconds } : {}),
482
+ ...(entry.config.pool.minIdle !== undefined ? { minIdle: entry.config.pool.minIdle } : {}),
481
483
  },
482
484
  }
483
485
  : {}),
@@ -16,6 +16,12 @@ const authoring = new Set();
16
16
  export function authoringApp(path) {
17
17
  authoring.add(path);
18
18
  }
19
+ /* The test kit's host (mistri/testing, run from source) asks every refusal it answers to carry its cause, so a test
20
+ reads why a tenant member or a seeded role was refused without opening the host's log. The word alone is not
21
+ trusted: a process says it is a test (`NODE_ENV=test`) as well, so an environment file that carried the seam into a
22
+ deployment tells nobody anything. */
23
+ const TEST_REFUSAL_CAUSE = 'MISTRI_TEST_REFUSAL_CAUSE';
24
+ const causeForTests = (env = process.env) => env[TEST_REFUSAL_CAUSE] === 'source' && env.NODE_ENV === 'test';
19
25
  /** Mark this request as the author's own, when it is: see the module comment. */
20
26
  export function noteAuthorRequest(req, bound, administrator, apps) {
21
27
  if (administrator &&
@@ -81,5 +87,5 @@ export function reportRefusal(req, status, code, heard, error, always = false) {
81
87
  console.error(` because: ${reason}`);
82
88
  }
83
89
  // The innermost reason is the one that names the rule, the table or the column.
84
- return authors.has(req) ? reasons.at(-1) : undefined;
90
+ return authors.has(req) || causeForTests() ? reasons.at(-1) : undefined;
85
91
  }
@@ -2,6 +2,10 @@
2
2
  export interface PoolSize {
3
3
  read?: number;
4
4
  write?: number;
5
+ /** Seconds an idle connection stays open; the server's (`MISTRI_POOL_IDLE`), else five minutes, when absent. */
6
+ idleSeconds?: number;
7
+ /** Connections each pool keeps open through an idle spell; two readers and one writer when absent. */
8
+ minIdle?: number;
5
9
  }
6
10
  /**
7
11
  * Refused rather than clamped or ignored, as `writable` is: a number quietly
@@ -1,13 +1,15 @@
1
1
  /**
2
2
  * A connection's `"pool"` and `"replicas"` in tablewalk.json, checked where the file is read:
3
- * `{ "read": n, "write": m }`, each a whole number from 1 to 64 and either
4
- * one optional, on a PostgreSQL connection. Apart from the loader because
3
+ * `{ "read": n, "write": m, "idleSeconds": s, "minIdle": k }`: the sizes each a
4
+ * whole number from 1 to 64, the idle window whole seconds from 1 to a day, the
5
+ * warm count 0 to 64, every one optional, on a PostgreSQL connection. Apart from the loader because
5
6
  * the rule is the pool's (postgresPool.ts holds the bounds); the loader only
6
7
  * asks it, as it asks httpConnection.ts about an API's fields.
7
8
  */
8
- import { isReaderCount, MAX_READERS } from '../adapters/postgresPool.js';
9
+ import { isIdleSeconds, isMinIdle, isReaderCount, MAX_IDLE_SECONDS, MAX_READERS } from '../adapters/postgresPool.js';
9
10
  import { isWriterCount, MAX_WRITERS } from '../adapters/writeLanes.js';
10
11
  import { MAX_REPLICAS } from '../adapters/replicas.js';
12
+ const POOL_KEYS = ['read', 'write', 'idleSeconds', 'minIdle'];
11
13
  /**
12
14
  * Refused rather than clamped or ignored, as `writable` is: a number quietly
13
15
  * overridden is a capacity plan that is not the one in the file. An HTTP
@@ -28,12 +30,18 @@ export function poolOf(entry, http, path) {
28
30
  throw new Error(`${where} has "pool": ${JSON.stringify(written)}. It must be an object such as { "read": 16, "write": 8 }.`);
29
31
  }
30
32
  const pool = written;
31
- const stray = Object.keys(pool).find((key) => key !== 'read' && key !== 'write');
33
+ const stray = Object.keys(pool).find((key) => !POOL_KEYS.includes(key));
32
34
  if (stray !== undefined)
33
- throw new Error(`${where} has "pool.${stray}". A pool takes "read" and "write".`);
34
- if (pool.read === undefined && pool.write === undefined) {
35
+ throw new Error(`${where} has "pool.${stray}". A pool takes "read", "write", "idleSeconds" and "minIdle".`);
36
+ if (!POOL_KEYS.some((key) => pool[key] !== undefined)) {
35
37
  throw new Error(`${where} has an empty "pool". Say how many connections may read or write at once, such as { "read": 16, "write": 8 }.`);
36
38
  }
39
+ if (pool.idleSeconds !== undefined && !isIdleSeconds(pool.idleSeconds)) {
40
+ throw new Error(`${where} has "pool": { "idleSeconds": ${JSON.stringify(pool.idleSeconds)} }. It must be whole seconds from 1 to ${MAX_IDLE_SECONDS}, without quotes.`);
41
+ }
42
+ if (pool.minIdle !== undefined && !isMinIdle(pool.minIdle)) {
43
+ throw new Error(`${where} has "pool": { "minIdle": ${JSON.stringify(pool.minIdle)} }. It must be a whole number from 0 to ${MAX_READERS}, without quotes.`);
44
+ }
37
45
  if (pool.read !== undefined && !isReaderCount(pool.read)) {
38
46
  throw new Error(`${where} has "pool": { "read": ${JSON.stringify(pool.read)} }. It must be a whole number from 1 to ${MAX_READERS}, without quotes.`);
39
47
  }
@@ -45,7 +53,12 @@ export function poolOf(entry, http, path) {
45
53
  if (!/^postgres(ql)?:\/\//i.test(url))
46
54
  throw new Error(`${where} is not a PostgreSQL connection; SQLite has no pool. Remove "pool".`);
47
55
  }
48
- return { ...(pool.read !== undefined ? { read: pool.read } : {}), ...(pool.write !== undefined ? { write: pool.write } : {}) };
56
+ return {
57
+ ...(pool.read !== undefined ? { read: pool.read } : {}),
58
+ ...(pool.write !== undefined ? { write: pool.write } : {}),
59
+ ...(pool.idleSeconds !== undefined ? { idleSeconds: pool.idleSeconds } : {}),
60
+ ...(pool.minIdle !== undefined ? { minIdle: pool.minIdle } : {}),
61
+ };
49
62
  }
50
63
  /**
51
64
  * A connection's `"replicas"`: `["postgres://…", "${REPLICA_URL}", …]`, read
@@ -353,14 +353,19 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
353
353
  }
354
354
  const results = Array.from({ length: items.length });
355
355
  const queue = items.map((item, at) => ({ item, at }));
356
+ /* An item's route knows its own last wave, not the batch's: the others are
357
+ still queued, or between their reads, when it says so, and a tenant App's
358
+ fence that left with it refuses every read after (TenantReadContext.lastWave).
359
+ Only a batch of one is that route alone. */
360
+ const each = items.length === 1 ? options : { ...options, lastWave: undefined };
356
361
  const one = async () => {
357
362
  for (let next = queue.shift(); next; next = queue.shift()) {
358
363
  const page = run(next.item);
359
364
  const { def, text, limit, offset } = next.item;
360
365
  try {
361
366
  results[next.at] = (await (page
362
- ? dispatchResourceReadHttp('/api/run', Object.fromEntries(RUN_FIELDS.filter((field) => page[field] !== undefined).map((field) => [field, page[field]])), adapter, schema, options)
363
- : dispatchResourceReadHttp('/api/breakdown', { def, text, limit, offset }, adapter, schema, options)));
367
+ ? dispatchResourceReadHttp('/api/run', Object.fromEntries(RUN_FIELDS.filter((field) => page[field] !== undefined).map((field) => [field, page[field]])), adapter, schema, each)
368
+ : dispatchResourceReadHttp('/api/breakdown', { def, text, limit, offset }, adapter, schema, each)));
364
369
  }
365
370
  catch (error) {
366
371
  /* A request's own refusal (a ResourceReadError: the provider's are
@@ -428,7 +428,7 @@ export function parsePage(raw, at) {
428
428
  params.length > MAX_PAGE_PARAMS ||
429
429
  params.some((name) => typeof name !== 'string' || !PARAM.test(name)) ||
430
430
  params.includes('period')) {
431
- throw new Error(`[page-params] ${at} has "params" that are not up to ${MAX_PAGE_PARAMS} lowercase words, each 'id', 'text', 'date', 'date-range' or a list of its values, like params: { list: 'id' }; "period" is a dashboard's.`);
431
+ throw new Error(`[page-params] ${at} has "params" that are not up to ${MAX_PAGE_PARAMS} lowercase words, each 'id', 'text', 'date', 'date-range' or a list of its values, like params: { list: 'id' }; "period" is a dashboard's address word, so a page's own window is named "window": params: { window: ['last-30-days', 'last-90-days'] }, read by a windowed <Metric window="window" over="close_date" previous spark />.`);
432
432
  }
433
433
  if (raw.loader !== undefined && (typeof raw.loader !== 'string' || !LOADER.test(raw.loader))) {
434
434
  throw new Error(`[page-loader] ${at} has a "loader" that is not a loader's name, as the commands module's defineLoaders() registers it.`);
@@ -25,12 +25,36 @@ export declare function unitForSpan(days: number): AutoUnit;
25
25
  export declare function readUnit(base: AutoUnit, addsUp: boolean): AutoUnit;
26
26
  /** The label of the period a day, month or quarter label falls in, spelled as the server spells it. */
27
27
  export declare function bucketKey(key: string, unit: AutoUnit, weekStart?: number): string;
28
+ interface FillOptions {
29
+ /** The unit the rows are keyed in: their keys are spelled as the server spells it (`2026-03-14`, `2026-03`, `2026-Q1`). */
30
+ unit: AutoUnit;
31
+ /** The first instant to fill from, its period included; absent, the first row's. */
32
+ from?: Date;
33
+ /** The last instant to fill to, its period included; absent, the last row's. */
34
+ to?: Date;
35
+ /** The zone `from` and `to` are read in, the App's: absent, their local fields. */
36
+ timeZone?: string;
37
+ /** The field a row's period is under: `key`, or the server's name for it (`day(created_at)`). */
38
+ key?: string;
39
+ /** The fields a filled period holds as 0: absent, the first row's numeric ones, else `value`. */
40
+ zero?: readonly string[];
41
+ weekStart?: number;
42
+ }
43
+ /**
44
+ * Rows keyed by period with the periods that held no rows put back as zero, marked `filled: true`, from `from`'s
45
+ * period to `to`'s (or the rows' own first and last), in order. A count of nothing is 0: a line drawn through only
46
+ * the days that had rows said a quiet week was a steady one. The periods are the App's calendar's (`timeZone`), so a
47
+ * moment near midnight falls on the day the people using the App say it did. Rows whose keys the unit does not spell
48
+ * come back as they came; only a count or a sum is honestly filled with 0, which the caller decides.
49
+ */
50
+ export declare function fillBuckets<R extends Record<string, unknown>>(rows: readonly R[], { unit, from, to, timeZone, key, zero, weekStart }: FillOptions): Array<R | (Record<string, unknown> & {
51
+ filled: true;
52
+ })>;
28
53
  /**
29
- * A trend's points over its window: the periods that held no rows put back as zero, from the window's first period
30
- * to today's, and the read periods added up into the unit the span is drawn in. A count of nothing is 0, and a line
31
- * drawn through only the days that had rows said a quiet week was a steady one; three busy days of a week drew no
32
- * line at all. Only a count or a sum adds up so: any other measure's points are drawn as read, and labels the read
33
- * unit does not spell are left as they came.
54
+ * A trend's points over its window: the periods that held no rows put back as zero (`fillBuckets`), from the window's
55
+ * first period to today's, and the read periods added up into the unit the span is drawn in. Three busy days of a
56
+ * week drew no line at all before. Only a count or a sum adds up so: any other measure's points are drawn as read,
57
+ * and labels the read unit does not spell are left as they came.
34
58
  */
35
59
  export declare function trendPoints<R extends {
36
60
  key: unknown;
@@ -131,28 +131,63 @@ const SPELLED = {
131
131
  };
132
132
  /** The local calendar day of a date, as the server spells a day. */
133
133
  const localDay = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
134
+ /** The calendar day an instant falls on in a zone, as the server spells a day; with no zone, its local fields (the wall
135
+ clock `dateWindow` computes a zoned window in, `zonedNow`). */
136
+ function dayIn(d, timeZone) {
137
+ if (!timeZone)
138
+ return localDay(d);
139
+ const parts = new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(d);
140
+ const get = (type) => parts.find((p) => p.type === type)?.value ?? '';
141
+ return `${get('year')}-${get('month')}-${get('day')}`;
142
+ }
143
+ /** The label of the period an instant falls in, in a zone. */
144
+ const periodOf = (d, unit, timeZone, weekStart) => bucketKey(dayIn(d, timeZone), unit, weekStart);
134
145
  /**
135
- * A trend's points over its window: the periods that held no rows put back as zero, from the window's first period
136
- * to today's, and the read periods added up into the unit the span is drawn in. A count of nothing is 0, and a line
137
- * drawn through only the days that had rows said a quiet week was a steady one; three busy days of a week drew no
138
- * line at all. Only a count or a sum adds up so: any other measure's points are drawn as read, and labels the read
139
- * unit does not spell are left as they came.
146
+ * Rows keyed by period with the periods that held no rows put back as zero, marked `filled: true`, from `from`'s
147
+ * period to `to`'s (or the rows' own first and last), in order. A count of nothing is 0: a line drawn through only
148
+ * the days that had rows said a quiet week was a steady one. The periods are the App's calendar's (`timeZone`), so a
149
+ * moment near midnight falls on the day the people using the App say it did. Rows whose keys the unit does not spell
150
+ * come back as they came; only a count or a sum is honestly filled with 0, which the caller decides.
151
+ */
152
+ export function fillBuckets(rows, { unit, from, to, timeZone, key = 'key', zero, weekStart = 1 }) {
153
+ const keys = rows.map((row) => String(row[key] ?? ''));
154
+ if (keys.some((k) => !SPELLED[unit].test(k)))
155
+ return [...rows];
156
+ const ends = [from, to].flatMap((d) => (d ? [periodOf(d, unit, timeZone, weekStart)] : []));
157
+ const sorted = [...keys, ...ends].sort();
158
+ if (!sorted.length)
159
+ return [...rows];
160
+ const numeric = rows.length ? Object.keys(rows[0]).filter((field) => field !== key && typeof rows[0][field] === 'number') : [];
161
+ const zeros = Object.fromEntries((zero ?? (numeric.length ? numeric : ['value'])).map((field) => [field, 0]));
162
+ const held = new Map(rows.map((row, i) => [keys[i], row]));
163
+ const out = [];
164
+ for (let at = sorted[0], n = 0; at <= sorted[sorted.length - 1] && n < 5000; at = nextKey(at, unit), n++)
165
+ /* The period first, as the server writes a row: the hook reads a row's measure as the column after its groups. */
166
+ out.push(held.get(at) ?? { [key]: at, ...zeros, filled: true });
167
+ return out;
168
+ }
169
+ /**
170
+ * A trend's points over its window: the periods that held no rows put back as zero (`fillBuckets`), from the window's
171
+ * first period to today's, and the read periods added up into the unit the span is drawn in. Three busy days of a
172
+ * week drew no line at all before. Only a count or a sum adds up so: any other measure's points are drawn as read,
173
+ * and labels the read unit does not spell are left as they came.
140
174
  */
141
175
  export function trendPoints(rows, read, unit, measure, window, now) {
142
176
  if (!/^(count|sum\s+[\w.$+]+)(\s+as\s+[\w$]+)?$/i.test((measure ?? 'count').trim()))
143
177
  return [...rows];
144
- const keys = rows.map((row) => String(row.key ?? ''));
145
- if (keys.some((key) => !SPELLED[read].test(key)))
178
+ const keyed = rows.map((row) => ({ key: String(row.key ?? ''), value: Number(row.value) || 0 }));
179
+ if (keyed.some((row) => !SPELLED[read].test(row.key)))
146
180
  return [...rows];
147
- const ends = window ? [window.start, new Date(Math.min(window.end.getTime() - 1, now.getTime()))] : [];
148
- const sorted = [...keys, ...ends.map((d) => bucketKey(localDay(d), read))].sort();
149
- if (!sorted.length)
181
+ if (!keyed.length && !window)
150
182
  return [...rows];
151
- const held = new Map(rows.map((row) => [String(row.key), Number(row.value) || 0]));
183
+ const filled = fillBuckets(keyed, {
184
+ unit: read,
185
+ ...(window ? { from: window.start, to: new Date(Math.min(window.end.getTime() - 1, now.getTime())) } : {}),
186
+ });
152
187
  const into = new Map();
153
- for (let key = sorted[0], n = 0; key <= sorted[sorted.length - 1] && n < 5000; key = nextKey(key, read), n++) {
154
- const label = bucketKey(key, unit);
155
- into.set(label, (into.get(label) ?? 0) + (held.get(key) ?? 0));
188
+ for (const row of filled) {
189
+ const label = bucketKey(String(row.key), unit);
190
+ into.set(label, (into.get(label) ?? 0) + (Number(row.value) || 0));
156
191
  }
157
192
  return [...into].map(([key, value]) => ({ key, value }));
158
193
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mistriwork/engine",
3
- "version": "1.0.0-rc.75",
3
+ "version": "1.0.0-rc.77",
4
4
  "description": "The engine both products stand on: the adapters (SQLite, Postgres), the catalog, the query language, keyset pages, the HTTP kit and the shared rules. No React.",
5
5
  "homepage": "https://mistriwork.dev",
6
6
  "bugs": {