@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/src/index.ts CHANGED
@@ -1,8 +1,21 @@
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 {
5
+ type Config,
6
+ type ConfigLayer,
7
+ type ConfigValue,
8
+ type DeepPartial,
9
+ type FromEnv,
10
+ fromEnv,
11
+ required,
12
+ type Setting,
13
+ type Source,
14
+ secret,
15
+ type Validate,
16
+ validate,
17
+ } from './config.ts'
18
+ export type { ConsoleFormat, ConsoleTime } from './console.ts'
6
19
  export * from './errors.ts'
7
20
  export type { Page } from './handles.ts'
8
21
  export type {
@@ -32,7 +45,7 @@ export type {
32
45
  WriteOptions,
33
46
  } from './kv.ts'
34
47
  export type { Allowance, Limiter, LimiterOptions, Rate } from './limiter.ts'
35
- export { type Logger, type LoggerOptions, logger } from './logger.ts'
48
+ export { type ConsoleOut, type Logger, type LoggerOptions, logger } from './logger.ts'
36
49
  export {
37
50
  type Aggregate,
38
51
  type AggregateOp,
package/src/kv.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  // buckets of one value type by key, keys in branches, expiry by the store's
3
3
  // clock, versions that never repeat. A handle opens with its first call.
4
4
 
5
- import { Config, type ConfigOptions } from './config.ts'
5
+ import { Config, type ConfigLayer, type ConfigValue } from './config.ts'
6
6
  import type { Connection, Link } from './connection.ts'
7
7
  import { ConflictError, CorruptError, InvalidError } from './errors.ts'
8
8
  import { checkName, handleOn, ownerText, type Page, type Settled, settle } from './handles.ts'
@@ -91,23 +91,27 @@ export class Kv {
91
91
  }
92
92
 
93
93
  /**
94
- * The config name, shaped and typed as its defaults: then a file's values,
95
- * then the environment, then what update kept, each over the one before.
96
- * It resolves once the server's state is read, and follows every change
97
- * from then on, whoever makes it, until the store closes.
94
+ * The config name, shaped and typed as its defaults, then each layer over
95
+ * the one before: a file's values, `fromEnv`, and what update kept over
96
+ * them all. It resolves once the server's state is read, and follows every
97
+ * change from then on, whoever makes it, until the store closes.
98
98
  *
99
99
  * ```ts
100
- * const cfg = await store.kv.config('app', { port: 8080, origins: ['localhost'] })
101
- * cfg.value.port // PORT=3000 in .env makes it 3000
100
+ * const cfg = await store.kv.config('app', {
101
+ * port: 8080,
102
+ * db: { url: secret('DATABASE_URL'), pool: 10 },
103
+ * }, file, fromEnv('APP'))
104
+ * cfg.value.port // APP_PORT=3000 makes it 3000
102
105
  * await cfg.update({ port: 4000 }) // kept: 4000 after a restart too
103
106
  * ```
104
107
  */
105
- async config<T extends object>(
108
+ async config<D extends object>(
106
109
  name: string,
107
- defaults: T,
108
- options: ConfigOptions<T> = {},
109
- ): Promise<Config<T>> {
110
- const config = new Config(this.#link, name, defaults, options)
110
+ defaults: D,
111
+ ...layers: ConfigLayer<ConfigValue<D>>[]
112
+ ): Promise<Config<ConfigValue<D>>> {
113
+ const config = new Config<ConfigValue<D>>(this.#link, name, defaults)
114
+ await config.lay(layers)
111
115
  this.#configs.add(config as unknown as Config<object>)
112
116
  try {
113
117
  await config.start()
package/src/logger.ts CHANGED
@@ -9,8 +9,10 @@ import { DropNotice, FailureLog, type Say } from './background.ts'
9
9
  import {
10
10
  type ConsoleFormat,
11
11
  type ConsoleLine,
12
+ type ConsoleTime,
12
13
  jsonLine,
13
14
  jsonOf,
15
+ type Look,
14
16
  prettyLine,
15
17
  redacted,
16
18
  redactor,
@@ -26,13 +28,17 @@ export interface LoggerOptions {
26
28
  level?: Level
27
29
  /** how a line is written as it is logged: pretty on a terminal and JSON otherwise when absent */
28
30
  console?: ConsoleFormat
31
+ /** how a pretty line shows its time: 'clock' when absent */
32
+ time?: ConsoleTime
33
+ /** leaves the stream out of a pretty line; the record keeps it */
34
+ hideStream?: boolean
35
+ /** where the console lines go: process.stderr when absent */
36
+ to?: ConsoleOut
29
37
  /** fields whose values are hidden, in the store and on the console, at any depth, the case ignored */
30
38
  redact?: readonly string[]
31
- /** the console lines go to stdout rather than stderr */
32
- stdout?: boolean
33
39
  }
34
40
 
35
- /** Where a console line goes: a process's stream, or a test's. */
41
+ /** Where console lines go: process.stdout, a file's stream, or any other writer. */
36
42
  export interface ConsoleOut {
37
43
  write(text: string): unknown
38
44
  readonly isTTY?: boolean
@@ -87,13 +93,14 @@ export function newLogger(
87
93
  if (!Number.isInteger(most) || most < 1) {
88
94
  throw new InvalidError(`a logger's buffer of ${most} lines`)
89
95
  }
96
+ const [read, ignored] = fromEnvironment(options)
90
97
  const shared: Shared = {
91
98
  append,
92
99
  stream,
93
100
  most,
94
- least: options.level === undefined ? Number.NEGATIVE_INFINITY : levelOf(options.level),
95
- hides: redactor(options.redact),
96
- print: printer(options, out),
101
+ least: read.level === undefined ? Number.NEGATIVE_INFINITY : levelOf(read.level),
102
+ hides: redactor(read.redact),
103
+ print: printer(read, out),
97
104
  waiting: [],
98
105
  timer: undefined,
99
106
  writing: undefined,
@@ -101,9 +108,71 @@ export function newLogger(
101
108
  failures: append === undefined ? undefined : new FailureLog(`records flush ${stream}`, sayOwn),
102
109
  drops: append === undefined ? undefined : new DropNotice(stream, most, sayOwn),
103
110
  }
111
+ sayIgnored(shared.print, ignored)
104
112
  return new Logger(shared, [])
105
113
  }
106
114
 
115
+ type Unread = [name: string, value: string, expected: string]
116
+
117
+ /** LOG_LEVEL, LOG_FORMAT and LOG_TIME over the options, as Go and Python read them; a console turned off stays off. */
118
+ function fromEnvironment(options: LoggerOptions): [LoggerOptions, Unread[]] {
119
+ const read = { ...options }
120
+ const ignored: Unread[] = []
121
+ const level = variable('LOG_LEVEL')
122
+ if (level !== undefined) {
123
+ const name = level.toLowerCase() === 'warning' ? 'warn' : level.toLowerCase()
124
+ if (Object.hasOwn(levels, name)) {
125
+ read.level = name as keyof typeof levels
126
+ } else {
127
+ ignored.push(['LOG_LEVEL', level, 'debug, info, warn or error'])
128
+ }
129
+ }
130
+ const format = variable('LOG_FORMAT')
131
+ if (format !== undefined) {
132
+ const name = format.toLowerCase()
133
+ if (name !== 'pretty' && name !== 'json' && name !== 'off') {
134
+ ignored.push(['LOG_FORMAT', format, 'pretty, json or off'])
135
+ } else if (read.console !== 'off') {
136
+ read.console = name
137
+ }
138
+ }
139
+ const time = variable('LOG_TIME')
140
+ if (time !== undefined) {
141
+ const name = time.toLowerCase()
142
+ if (name === 'clock' || name === 'full' || name === 'off') {
143
+ read.time = name
144
+ } else {
145
+ ignored.push(['LOG_TIME', time, 'clock, full or off'])
146
+ }
147
+ }
148
+ return [read, ignored]
149
+ }
150
+
151
+ function variable(name: string): string | undefined {
152
+ const text = process.env[name]?.trim()
153
+ return text === '' ? undefined : text
154
+ }
155
+
156
+ /** The values said to be ignored, so that a program making many loggers says each once. */
157
+ const saidIgnored = new Set<string>()
158
+
159
+ function sayIgnored(print: Shared['print'], ignored: Unread[]): void {
160
+ for (const [name, value, expected] of ignored) {
161
+ if (print === undefined || saidIgnored.has(`${name}=${value}`)) {
162
+ continue
163
+ }
164
+ saidIgnored.add(`${name}=${value}`)
165
+ print({
166
+ at: new Date(),
167
+ stream: 'tinystore',
168
+ level: levels.warn,
169
+ msg: `${name} is ignored`,
170
+ context: [],
171
+ attrs: ['value', JSON.stringify(value), 'expected', JSON.stringify(expected)],
172
+ })
173
+ }
174
+ }
175
+
107
176
  let own: Logger | undefined
108
177
 
109
178
  /** TinyStore's own lines, on the console of a logger of stream tinystore made when first needed. */
@@ -112,20 +181,36 @@ export const sayOwn: Say = (level, message, fields) => {
112
181
  own[level](message, fields)
113
182
  }
114
183
 
184
+ function forceColor(): boolean {
185
+ const force = process.env.FORCE_COLOR
186
+ return force !== undefined && force !== '' && force !== '0'
187
+ }
188
+
115
189
  /** How a logger prints its lines, or undefined when it prints none. */
116
190
  function printer(options: LoggerOptions, out?: ConsoleOut & { utc?: boolean }): Shared['print'] {
117
191
  if (options.console === 'off') {
118
192
  return undefined
119
193
  }
120
- const stream: ConsoleOut = out ?? (options.stdout === true ? process.stdout : process.stderr)
194
+ const stream: ConsoleOut = out ?? options.to ?? process.stderr
195
+ // FORCE_COLOR other than 0 says a person reads a pipe, as an IDE's run console is one
196
+ const forced = out === undefined && forceColor()
121
197
  const terminal = stream.isTTY === true
122
- const pretty = options.console === 'pretty' || (options.console === undefined && terminal)
198
+ const pretty =
199
+ options.console === 'pretty' || (options.console === undefined && (terminal || forced))
123
200
  if (!pretty) {
124
201
  return line => void stream.write(jsonLine(line))
125
202
  }
126
203
  const color =
127
- terminal && out === undefined && !process.env.NO_COLOR && process.env.TERM !== 'dumb'
128
- return line => void stream.write(prettyLine(line, color, out?.utc === true))
204
+ (forced || (terminal && out === undefined)) &&
205
+ !process.env.NO_COLOR &&
206
+ process.env.TERM !== 'dumb'
207
+ const look: Look = {
208
+ color,
209
+ utc: out?.utc === true,
210
+ time: options.time,
211
+ hideStream: options.hideStream,
212
+ }
213
+ return line => void stream.write(prettyLine(line, look))
129
214
  }
130
215
 
131
216
  /**
package/src/sql.ts 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
 
6
6
  import { readdir, readFile } from 'node:fs/promises'
7
7
  import { join } from 'node:path'
package/src/store.ts CHANGED
@@ -98,7 +98,9 @@ export class Store implements AsyncDisposable {
98
98
  /**
99
99
  * Opens a database of the application's own, sql/<name>.db. The first open
100
100
  * in the server, on an admin connection, applies its migrations; every
101
- * later one checks them against what the file applied.
101
+ * later one checks them against what the file applied. Without migrations
102
+ * it opens the file as it is, an empty one if there is none, and checks
103
+ * nothing.
102
104
  */
103
105
  sql(name: string, options?: SqlOptions): Promise<Database> {
104
106
  return openDatabase(this.#link, name, options)
@@ -178,6 +180,7 @@ export async function openWith(
178
180
  dir: string,
179
181
  options: OpenOptions = {},
180
182
  ): Promise<Store> {
183
+ checkDirectory(dir)
181
184
  const binary = () => findBinary(runtime, options.binary)
182
185
  const idle = options.idle === undefined ? undefined : ms(options.idle)
183
186
  if (options.clock !== undefined && options.private !== true) {
@@ -206,6 +209,31 @@ export async function connect(url: string, options: ConnectOptions): Promise<Sto
206
209
  return new Store(link)
207
210
  }
208
211
 
212
+ // two letters or more before a colon: an address, never a Windows drive
213
+ const address = /^([a-z][a-z0-9+.-]+):/i
214
+
215
+ /**
216
+ * Refuses an address where a directory belongs: open('tcp://…') would make a
217
+ * folder of that name and start a server in it, rather than reach the one meant.
218
+ *
219
+ * open('tcp://db.internal:7070') → use connect
220
+ * open('pipe:tinystore-d761f24b7e59') → open the directory it serves
221
+ * open('C:/data') → a directory
222
+ */
223
+ function checkDirectory(dir: string): void {
224
+ const scheme = address.exec(dir)?.[1]?.toLowerCase()
225
+ if (scheme === 'tcp' || scheme === 'tls') {
226
+ throw new InvalidError(
227
+ `open takes a store's directory, and ${dir} is a server's address: connect('${dir}', { token }) reaches it`,
228
+ )
229
+ }
230
+ if (scheme !== undefined) {
231
+ throw new InvalidError(
232
+ `open takes a store's directory, and ${dir} is an address: open the directory its server serves, and it is found through SERVE`,
233
+ )
234
+ }
235
+ }
236
+
209
237
  function findBinary(runtime: Runtime, given: string | undefined): string {
210
238
  const found =
211
239
  given ?? process.env.TINYSTORE_BIN ?? runtime.packagedBinary() ?? runtime.which('tinystore')