@tinyshed/tinystore 0.1.0-rc.2 → 0.1.0-rc.4

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.
package/dist/console.js CHANGED
@@ -50,16 +50,22 @@ const cyan = '\x1b[36m';
50
50
  * traceback, follows the line, indented. A key or a string shows without its
51
51
  * quotes when it is one word with no '=', quote or backslash.
52
52
  */
53
- export function prettyLine(line, color, utc = false) {
54
- const paint = (hue, text) => (color ? hue + text + reset : text);
53
+ export function prettyLine(line, look) {
54
+ const paint = (hue, text) => (look.color ? hue + text + reset : text);
55
55
  const [label, hue] = prettyLevel(line.level);
56
- let out = `${paint(dim, clock(line.at, utc))} ${paint(hue, label)}${' '.repeat(Math.max(0, 5 - label.length))}`;
57
- out += ` ${paint(cyan, line.stream)}`;
56
+ let out = look.time === 'off' ? '' : `${paint(dim, stamp(line.at, look))} `;
57
+ out += paint(hue, label);
58
+ // the level is padded to five; the columns after it are two spaces apart
59
+ let separator = `${' '.repeat(Math.max(0, 5 - label.length))} `;
60
+ if (look.hideStream !== true) {
61
+ out += `${separator}${paint(cyan, line.stream)}`;
62
+ separator = ' ';
63
+ }
58
64
  const message = prettyMessage(line);
59
65
  if (message !== '') {
60
- out += ` ${message}`;
66
+ out += `${separator}${message}`;
67
+ separator = ' ';
61
68
  }
62
- let separator = ' ';
63
69
  const field = (key, text) => {
64
70
  out += `${separator}${paint(dim, `${bare(key) ? key : JSON.stringify(key)}=`)}${text}`;
65
71
  separator = ' ';
@@ -145,12 +151,36 @@ function bare(text) {
145
151
  }
146
152
  return true;
147
153
  }
148
- function clock(at, utc) {
149
- const parts = utc
150
- ? [at.getUTCHours(), at.getUTCMinutes(), at.getUTCSeconds()]
151
- : [at.getHours(), at.getMinutes(), at.getSeconds()];
152
- const millis = utc ? at.getUTCMilliseconds() : at.getMilliseconds();
153
- return `${parts.map(n => String(n).padStart(2, '0')).join(':')}.${String(millis).padStart(3, '0')}`;
154
+ /** The time of day, or with the date and zone in full: 2026-10-02 11:02:11.123 +03:00. */
155
+ function stamp(at, look) {
156
+ const utc = look.utc === true;
157
+ const [year, month, day, hours, minutes, seconds, millis] = utc
158
+ ? [
159
+ at.getUTCFullYear(),
160
+ at.getUTCMonth() + 1,
161
+ at.getUTCDate(),
162
+ at.getUTCHours(),
163
+ at.getUTCMinutes(),
164
+ at.getUTCSeconds(),
165
+ at.getUTCMilliseconds(),
166
+ ]
167
+ : [
168
+ at.getFullYear(),
169
+ at.getMonth() + 1,
170
+ at.getDate(),
171
+ at.getHours(),
172
+ at.getMinutes(),
173
+ at.getSeconds(),
174
+ at.getMilliseconds(),
175
+ ];
176
+ const two = (n) => String(n).padStart(2, '0');
177
+ const clock = `${two(hours)}:${two(minutes)}:${two(seconds)}.${String(millis).padStart(3, '0')}`;
178
+ if (look.time !== 'full') {
179
+ return clock;
180
+ }
181
+ const offset = utc ? 0 : -at.getTimezoneOffset();
182
+ const zone = `${offset < 0 ? '-' : '+'}${two(Math.trunc(Math.abs(offset) / 60))}:${two(Math.abs(offset) % 60)}`;
183
+ return `${String(year).padStart(4, '0')}-${two(month)}-${two(day)} ${clock} ${zone}`;
154
184
  }
155
185
  /**
156
186
  * Says whether a field's key hides its value: the key, or the part of a dotted
package/dist/index.d.ts CHANGED
@@ -1,14 +1,14 @@
1
1
  export type { BlobBucket, BlobObject, Blobs, Body, Download, PutOptions } from './blobs.ts';
2
2
  export { withSignal } from './cancel.ts';
3
3
  export type { Clock } from './clock.ts';
4
- export type { Config, ConfigOptions, DeepPartial, Source } from './config.ts';
5
- export type { ConsoleFormat } from './console.ts';
4
+ export { type Config, type ConfigLayer, type ConfigValue, type DeepPartial, type FromEnv, fromEnv, required, type Setting, type Source, secret, type Validate, validate, } from './config.ts';
5
+ export type { ConsoleFormat, ConsoleTime } from './console.ts';
6
6
  export * from './errors.ts';
7
7
  export type { Page } from './handles.ts';
8
8
  export type { ClaimedJob, EnqueueOptions, Job, JobEntry, JobState, Jobs, Queue, QueueOptions, QueueTx, Repeat, WorkOptions, } from './jobs.ts';
9
9
  export type { Batch, Bucket, BucketOptions, BucketTx, CounterOptions, Counters, Entry, Kind, Scanned, Tx, WriteOptions, } from './kv.ts';
10
10
  export type { Allowance, Limiter, LimiterOptions, Rate } from './limiter.ts';
11
- export { type Logger, type LoggerOptions, logger } from './logger.ts';
11
+ export { type ConsoleOut, type Logger, type LoggerOptions, logger } from './logger.ts';
12
12
  export { type Aggregate, type AggregateOp, type AggregateRange, type Bucket as MetricsBucket, Condition, type Counter, type Gauge, type Labels, type Metrics, noneOf, oneOf, type Plan, prefix, type Range, type Series, type SeriesInput, type SeriesKind, type Timer, } from './metrics.ts';
13
13
  export type { Once, OnceOptions } from './once.ts';
14
14
  export type { Quota, QuotaUsage, WindowUsage } from './quota.ts';
package/dist/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export { withSignal } from './cancel.js';
2
+ export { fromEnv, required, secret, validate, } from './config.js';
2
3
  export * from './errors.js';
3
4
  export { logger } from './logger.js';
4
5
  export { Condition, noneOf, oneOf, prefix, } from './metrics.js';
package/dist/kv.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { Config, type ConfigOptions } from './config.ts';
1
+ import { Config, type ConfigLayer, type ConfigValue } from './config.ts';
2
2
  import type { Link } from './connection.ts';
3
3
  import { type Page, type Settled } from './handles.ts';
4
4
  import { Limiter, type LimiterOptions, type Rate } from './limiter.ts';
@@ -72,18 +72,21 @@ export declare class Kv {
72
72
  #private;
73
73
  constructor(link: Link);
74
74
  /**
75
- * The config name, shaped and typed as its defaults: then a file's values,
76
- * then the environment, then what update kept, each over the one before.
77
- * It resolves once the server's state is read, and follows every change
78
- * from then on, whoever makes it, until the store closes.
75
+ * The config name, shaped and typed as its defaults, then each layer over
76
+ * the one before: a file's values, `fromEnv`, and what update kept over
77
+ * them all. It resolves once the server's state is read, and follows every
78
+ * change from then on, whoever makes it, until the store closes.
79
79
  *
80
80
  * ```ts
81
- * const cfg = await store.kv.config('app', { port: 8080, origins: ['localhost'] })
82
- * cfg.value.port // PORT=3000 in .env makes it 3000
81
+ * const cfg = await store.kv.config('app', {
82
+ * port: 8080,
83
+ * db: { url: secret('DATABASE_URL'), pool: 10 },
84
+ * }, file, fromEnv('APP'))
85
+ * cfg.value.port // APP_PORT=3000 makes it 3000
83
86
  * await cfg.update({ port: 4000 }) // kept: 4000 after a restart too
84
87
  * ```
85
88
  */
86
- config<T extends object>(name: string, defaults: T, options?: ConfigOptions<T>): Promise<Config<T>>;
89
+ config<D extends object>(name: string, defaults: D, ...layers: ConfigLayer<ConfigValue<D>>[]): Promise<Config<ConfigValue<D>>>;
87
90
  /** A limiter of requests by key: `store.kv.limiter('api', { rate: '100/s', burst: 20 })`. */
88
91
  limiter(name: string, options: LimiterOptions): Limiter;
89
92
  /**
package/dist/kv.js CHANGED
@@ -18,19 +18,23 @@ export class Kv {
18
18
  this.#link = link;
19
19
  }
20
20
  /**
21
- * The config name, shaped and typed as its defaults: then a file's values,
22
- * then the environment, then what update kept, each over the one before.
23
- * It resolves once the server's state is read, and follows every change
24
- * from then on, whoever makes it, until the store closes.
21
+ * The config name, shaped and typed as its defaults, then each layer over
22
+ * the one before: a file's values, `fromEnv`, and what update kept over
23
+ * them all. It resolves once the server's state is read, and follows every
24
+ * change from then on, whoever makes it, until the store closes.
25
25
  *
26
26
  * ```ts
27
- * const cfg = await store.kv.config('app', { port: 8080, origins: ['localhost'] })
28
- * cfg.value.port // PORT=3000 in .env makes it 3000
27
+ * const cfg = await store.kv.config('app', {
28
+ * port: 8080,
29
+ * db: { url: secret('DATABASE_URL'), pool: 10 },
30
+ * }, file, fromEnv('APP'))
31
+ * cfg.value.port // APP_PORT=3000 makes it 3000
29
32
  * await cfg.update({ port: 4000 }) // kept: 4000 after a restart too
30
33
  * ```
31
34
  */
32
- async config(name, defaults, options = {}) {
33
- const config = new Config(this.#link, name, defaults, options);
35
+ async config(name, defaults, ...layers) {
36
+ const config = new Config(this.#link, name, defaults);
37
+ await config.lay(layers);
34
38
  this.#configs.add(config);
35
39
  try {
36
40
  await config.start();
package/dist/logger.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { DropNotice, FailureLog, type Say } from './background.ts';
2
- import { type ConsoleFormat, type ConsoleLine } from './console.ts';
2
+ import { type ConsoleFormat, type ConsoleLine, type ConsoleTime } from './console.ts';
3
3
  import type { Fields, Level } from './records.ts';
4
4
  export interface LoggerOptions {
5
5
  /** the lines held between writes; past it a line is dropped and counted: 1024 */
@@ -8,12 +8,16 @@ export interface LoggerOptions {
8
8
  level?: Level;
9
9
  /** how a line is written as it is logged: pretty on a terminal and JSON otherwise when absent */
10
10
  console?: ConsoleFormat;
11
+ /** how a pretty line shows its time: 'clock' when absent */
12
+ time?: ConsoleTime;
13
+ /** leaves the stream out of a pretty line; the record keeps it */
14
+ hideStream?: boolean;
15
+ /** where the console lines go: process.stderr when absent */
16
+ to?: ConsoleOut;
11
17
  /** fields whose values are hidden, in the store and on the console, at any depth, the case ignored */
12
18
  redact?: readonly string[];
13
- /** the console lines go to stdout rather than stderr */
14
- stdout?: boolean;
15
19
  }
16
- /** Where a console line goes: a process's stream, or a test's. */
20
+ /** Where console lines go: process.stdout, a file's stream, or any other writer. */
17
21
  export interface ConsoleOut {
18
22
  write(text: string): unknown;
19
23
  readonly isTTY?: boolean;
package/dist/logger.js CHANGED
@@ -32,13 +32,14 @@ export function newLogger(append, stream, options = {}, out) {
32
32
  if (!Number.isInteger(most) || most < 1) {
33
33
  throw new InvalidError(`a logger's buffer of ${most} lines`);
34
34
  }
35
+ const [read, ignored] = fromEnvironment(options);
35
36
  const shared = {
36
37
  append,
37
38
  stream,
38
39
  most,
39
- least: options.level === undefined ? Number.NEGATIVE_INFINITY : levelOf(options.level),
40
- hides: redactor(options.redact),
41
- print: printer(options, out),
40
+ least: read.level === undefined ? Number.NEGATIVE_INFINITY : levelOf(read.level),
41
+ hides: redactor(read.redact),
42
+ print: printer(read, out),
42
43
  waiting: [],
43
44
  timer: undefined,
44
45
  writing: undefined,
@@ -46,27 +47,100 @@ export function newLogger(append, stream, options = {}, out) {
46
47
  failures: append === undefined ? undefined : new FailureLog(`records flush ${stream}`, sayOwn),
47
48
  drops: append === undefined ? undefined : new DropNotice(stream, most, sayOwn),
48
49
  };
50
+ sayIgnored(shared.print, ignored);
49
51
  return new Logger(shared, []);
50
52
  }
53
+ /** LOG_LEVEL, LOG_FORMAT and LOG_TIME over the options, as Go and Python read them; a console turned off stays off. */
54
+ function fromEnvironment(options) {
55
+ const read = { ...options };
56
+ const ignored = [];
57
+ const level = variable('LOG_LEVEL');
58
+ if (level !== undefined) {
59
+ const name = level.toLowerCase() === 'warning' ? 'warn' : level.toLowerCase();
60
+ if (Object.hasOwn(levels, name)) {
61
+ read.level = name;
62
+ }
63
+ else {
64
+ ignored.push(['LOG_LEVEL', level, 'debug, info, warn or error']);
65
+ }
66
+ }
67
+ const format = variable('LOG_FORMAT');
68
+ if (format !== undefined) {
69
+ const name = format.toLowerCase();
70
+ if (name !== 'pretty' && name !== 'json' && name !== 'off') {
71
+ ignored.push(['LOG_FORMAT', format, 'pretty, json or off']);
72
+ }
73
+ else if (read.console !== 'off') {
74
+ read.console = name;
75
+ }
76
+ }
77
+ const time = variable('LOG_TIME');
78
+ if (time !== undefined) {
79
+ const name = time.toLowerCase();
80
+ if (name === 'clock' || name === 'full' || name === 'off') {
81
+ read.time = name;
82
+ }
83
+ else {
84
+ ignored.push(['LOG_TIME', time, 'clock, full or off']);
85
+ }
86
+ }
87
+ return [read, ignored];
88
+ }
89
+ function variable(name) {
90
+ const text = process.env[name]?.trim();
91
+ return text === '' ? undefined : text;
92
+ }
93
+ /** The values said to be ignored, so that a program making many loggers says each once. */
94
+ const saidIgnored = new Set();
95
+ function sayIgnored(print, ignored) {
96
+ for (const [name, value, expected] of ignored) {
97
+ if (print === undefined || saidIgnored.has(`${name}=${value}`)) {
98
+ continue;
99
+ }
100
+ saidIgnored.add(`${name}=${value}`);
101
+ print({
102
+ at: new Date(),
103
+ stream: 'tinystore',
104
+ level: levels.warn,
105
+ msg: `${name} is ignored`,
106
+ context: [],
107
+ attrs: ['value', JSON.stringify(value), 'expected', JSON.stringify(expected)],
108
+ });
109
+ }
110
+ }
51
111
  let own;
52
112
  /** TinyStore's own lines, on the console of a logger of stream tinystore made when first needed. */
53
113
  export const sayOwn = (level, message, fields) => {
54
114
  own ??= logger('tinystore');
55
115
  own[level](message, fields);
56
116
  };
117
+ function forceColor() {
118
+ const force = process.env.FORCE_COLOR;
119
+ return force !== undefined && force !== '' && force !== '0';
120
+ }
57
121
  /** How a logger prints its lines, or undefined when it prints none. */
58
122
  function printer(options, out) {
59
123
  if (options.console === 'off') {
60
124
  return undefined;
61
125
  }
62
- const stream = out ?? (options.stdout === true ? process.stdout : process.stderr);
126
+ const stream = out ?? options.to ?? process.stderr;
127
+ // FORCE_COLOR other than 0 says a person reads a pipe, as an IDE's run console is one
128
+ const forced = out === undefined && forceColor();
63
129
  const terminal = stream.isTTY === true;
64
- const pretty = options.console === 'pretty' || (options.console === undefined && terminal);
130
+ const pretty = options.console === 'pretty' || (options.console === undefined && (terminal || forced));
65
131
  if (!pretty) {
66
132
  return line => void stream.write(jsonLine(line));
67
133
  }
68
- const color = terminal && out === undefined && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
69
- return line => void stream.write(prettyLine(line, color, out?.utc === true));
134
+ const color = (forced || (terminal && out === undefined)) &&
135
+ !process.env.NO_COLOR &&
136
+ process.env.TERM !== 'dumb';
137
+ const look = {
138
+ color,
139
+ utc: out?.utc === true,
140
+ time: options.time,
141
+ hideStream: options.hideStream,
142
+ };
143
+ return line => void stream.write(prettyLine(line, look));
70
144
  }
71
145
  /**
72
146
  * A logger of one stream. `info`, `warn` and the rest return at once; a line
package/dist/sql.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // The application's own SQLite databases, sql/<name>.db, as Go's sqldb keeps
2
2
  // them: the application writes every query, the server owns the file, its
3
3
  // connections and its migrations, which the first open applies and every
4
- // later one checks.
4
+ // later one checks. An open without migrations takes the file as it is.
5
5
  import { readdir, readFile } from 'node:fs/promises';
6
6
  import { join } from 'node:path';
7
7
  import { InvalidError } from './errors.js';
package/dist/store.d.ts CHANGED
@@ -68,7 +68,9 @@ export declare class Store implements AsyncDisposable {
68
68
  /**
69
69
  * Opens a database of the application's own, sql/<name>.db. The first open
70
70
  * in the server, on an admin connection, applies its migrations; every
71
- * later one checks them against what the file applied.
71
+ * later one checks them against what the file applied. Without migrations
72
+ * it opens the file as it is, an empty one if there is none, and checks
73
+ * nothing.
72
74
  */
73
75
  sql(name: string, options?: SqlOptions): Promise<Database>;
74
76
  /**
package/dist/store.js CHANGED
@@ -53,7 +53,9 @@ export class Store {
53
53
  /**
54
54
  * Opens a database of the application's own, sql/<name>.db. The first open
55
55
  * in the server, on an admin connection, applies its migrations; every
56
- * later one checks them against what the file applied.
56
+ * later one checks them against what the file applied. Without migrations
57
+ * it opens the file as it is, an empty one if there is none, and checks
58
+ * nothing.
57
59
  */
58
60
  sql(name, options) {
59
61
  return openDatabase(this.#link, name, options);
@@ -121,6 +123,7 @@ export async function open(dir, options = {}) {
121
123
  return openWith(runtime, dir, options);
122
124
  }
123
125
  export async function openWith(runtime, dir, options = {}) {
126
+ checkDirectory(dir);
124
127
  const binary = () => findBinary(runtime, options.binary);
125
128
  const idle = options.idle === undefined ? undefined : ms(options.idle);
126
129
  if (options.clock !== undefined && options.private !== true) {
@@ -143,6 +146,25 @@ export async function connect(url, options) {
143
146
  await link.connection();
144
147
  return new Store(link);
145
148
  }
149
+ // two letters or more before a colon: an address, never a Windows drive
150
+ const address = /^([a-z][a-z0-9+.-]+):/i;
151
+ /**
152
+ * Refuses an address where a directory belongs: open('tcp://…') would make a
153
+ * folder of that name and start a server in it, rather than reach the one meant.
154
+ *
155
+ * open('tcp://db.internal:7070') → use connect
156
+ * open('pipe:tinystore-d761f24b7e59') → open the directory it serves
157
+ * open('C:/data') → a directory
158
+ */
159
+ function checkDirectory(dir) {
160
+ const scheme = address.exec(dir)?.[1]?.toLowerCase();
161
+ if (scheme === 'tcp' || scheme === 'tls') {
162
+ throw new InvalidError(`open takes a store's directory, and ${dir} is a server's address: connect('${dir}', { token }) reaches it`);
163
+ }
164
+ if (scheme !== undefined) {
165
+ throw new InvalidError(`open takes a store's directory, and ${dir} is an address: open the directory its server serves, and it is found through SERVE`);
166
+ }
167
+ }
146
168
  function findBinary(runtime, given) {
147
169
  const found = given ?? process.env.TINYSTORE_BIN ?? runtime.packagedBinary() ?? runtime.which('tinystore');
148
170
  if (found === undefined || found === '') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyshed/tinystore",
3
- "version": "0.1.0-rc.2",
3
+ "version": "0.1.0-rc.4",
4
4
  "description": "TinyStore for Bun and Node: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -30,11 +30,11 @@
30
30
  "README.md"
31
31
  ],
32
32
  "optionalDependencies": {
33
- "@tinyshed/tinystore-darwin-arm64": "0.1.0-rc.2",
34
- "@tinyshed/tinystore-darwin-x64": "0.1.0-rc.2",
35
- "@tinyshed/tinystore-linux-arm64": "0.1.0-rc.2",
36
- "@tinyshed/tinystore-linux-x64": "0.1.0-rc.2",
37
- "@tinyshed/tinystore-win32-arm64": "0.1.0-rc.2",
38
- "@tinyshed/tinystore-win32-x64": "0.1.0-rc.2"
33
+ "@tinyshed/tinystore-darwin-arm64": "0.1.0-rc.4",
34
+ "@tinyshed/tinystore-darwin-x64": "0.1.0-rc.4",
35
+ "@tinyshed/tinystore-linux-arm64": "0.1.0-rc.4",
36
+ "@tinyshed/tinystore-linux-x64": "0.1.0-rc.4",
37
+ "@tinyshed/tinystore-win32-arm64": "0.1.0-rc.4",
38
+ "@tinyshed/tinystore-win32-x64": "0.1.0-rc.4"
39
39
  }
40
40
  }