@tinyshed/tinystore 0.7.1 → 0.9.0

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/sql.ts CHANGED
@@ -91,6 +91,14 @@ export interface DatabaseOptions {
91
91
  * with it. A database open already keeps what it was opened with.
92
92
  */
93
93
  durability?: Durability
94
+ /**
95
+ * Whether backups take the database; `false` keeps its file and the
96
+ * bytes of its files in `local/` rather than `sql/`, where no backup
97
+ * looks, open or not, and no node copies it: each node that opens it
98
+ * writes its own. A name lives in one folder: one whose file lies in the
99
+ * other is InvalidError, naming both.
100
+ */
101
+ backup?: boolean
94
102
  }
95
103
 
96
104
  /** What a write changed: the rows, and SQLite's rowid of the row it inserted, 0 when none. */
@@ -133,15 +141,32 @@ export function grouped(text: string): boolean {
133
141
  if (!text.startsWith('(') || !text.endsWith(')')) {
134
142
  return /^[01]$/.test(text)
135
143
  }
144
+ // A parenthesis inside quotes or a comment counts for nothing: ('(') or ('x') is two groups, not one.
136
145
  let depth = 0
137
146
  for (let at = 0; at < text.length; at++) {
138
- if (text[at] === '(') depth++
139
- if (text[at] === ')') depth--
147
+ const c = text[at]!
148
+ if (c === "'" || c === '"' || c === '`') {
149
+ at = closing(text, at, c)
150
+ continue
151
+ }
152
+ if (c === '-' && text[at + 1] === '-') {
153
+ at = text.indexOf('\n', at)
154
+ if (at < 0) break
155
+ continue
156
+ }
157
+ if (c === '/' && text[at + 1] === '*') {
158
+ at = text.indexOf('*/', at + 2)
159
+ if (at < 0) break
160
+ at++
161
+ continue
162
+ }
163
+ if (c === '(') depth++
164
+ if (c === ')') depth--
140
165
  if (depth === 0 && at < text.length - 1) {
141
166
  return false
142
167
  }
143
168
  }
144
- return true
169
+ return depth === 0
145
170
  }
146
171
 
147
172
  /** Pieces joined with and or or, each in parentheses unless it may stand as it is. */
@@ -193,6 +218,53 @@ export function standsAlone(text: string): boolean {
193
218
  return true
194
219
  }
195
220
 
221
+ /**
222
+ * A piece as a query takes it. What the query writes after a piece, an and,
223
+ * a ), a desc or a where, must stay SQL: a piece that ends inside a --
224
+ * comment gets the newline that ends it, and one that ends inside a block
225
+ * comment, which only its closing mark ends, is refused.
226
+ */
227
+ export function checked(piece: Sql): Sql {
228
+ switch (commentAtEnd(piece.text)) {
229
+ case 'line':
230
+ return new Sql(`${piece.text}\n`, piece.values, piece.bare)
231
+ case 'block':
232
+ throw new InvalidError(
233
+ `a piece of SQL ends inside a /* comment, which would hide what the query writes after it: ${piece.text}`,
234
+ )
235
+ }
236
+ return piece
237
+ }
238
+
239
+ /** Text written into another piece, a -- comment at its end ended by a newline. */
240
+ function ended(text: string): string {
241
+ return commentAtEnd(text) === 'line' ? `${text}\n` : text
242
+ }
243
+
244
+ /**
245
+ * The comment text ends inside, outside quotes and brackets, if it ends
246
+ * inside one: `a = 1 -- why` ends inside a line comment.
247
+ */
248
+ function commentAtEnd(text: string): 'line' | 'block' | undefined {
249
+ for (let at = 0; at < text.length; at++) {
250
+ const c = text[at]!
251
+ if (c === "'" || c === '"' || c === '`') {
252
+ at = closing(text, at, c)
253
+ } else if (c === '[') {
254
+ at = text.indexOf(']', at + 1)
255
+ if (at < 0) return undefined
256
+ } else if (c === '-' && text[at + 1] === '-') {
257
+ at = text.indexOf('\n', at)
258
+ if (at < 0) return 'line'
259
+ } else if (c === '/' && text[at + 1] === '*') {
260
+ at = text.indexOf('*/', at + 2)
261
+ if (at < 0) return 'block'
262
+ at++
263
+ }
264
+ }
265
+ return undefined
266
+ }
267
+
196
268
  /** Something that writes itself as SQL inside another piece: a table's query. */
197
269
  export interface Embeddable {
198
270
  /** its text and values, wrapped as a subquery is */
@@ -228,7 +300,7 @@ function piece(first: TemplateStringsArray | string, values: unknown[]): Sql {
228
300
  const out: SqlArg[] = []
229
301
  values.forEach((value, at) => {
230
302
  if (value instanceof Sql) {
231
- text += value.text
303
+ text += ended(value.text)
232
304
  out.push(...value.values)
233
305
  } else if (isEmbeddable(value)) {
234
306
  const inner = value.embedded()
@@ -298,7 +370,7 @@ function listed(value: unknown): unknown {
298
370
  }
299
371
 
300
372
  function group(conditions: Condition[], joiner: 'or' | 'and', empty: string): Sql {
301
- const pieces = conditions.map(conditionOf)
373
+ const pieces = conditions.map(condition => checked(conditionOf(condition)))
302
374
  if (pieces.length === 0) {
303
375
  return new Sql(empty, [])
304
376
  }
@@ -423,7 +495,7 @@ export function placeholders(text: string): {
423
495
  return { positional, named, numbered }
424
496
  }
425
497
 
426
- /** The index past a quoted run that starts at `at`, a doubled quote inside it kept. */
498
+ /** The index of the quote that ends a quoted run starting at `at`, a doubled quote inside it kept. */
427
499
  function closing(text: string, at: number, quote: string): number {
428
500
  for (let next = at + 1; next < text.length; next++) {
429
501
  if (text[next] === quote) {
@@ -514,7 +586,8 @@ export async function openDatabase(
514
586
  checkDurability(options.durability, `sql ${name}`)
515
587
  const migrations =
516
588
  options.migrations === undefined ? undefined : await migrationFiles(options.migrations)
517
- const open = SqlOpen.encode({ name, migrations, durability: options.durability })
589
+ const backup = options.backup === false ? false : undefined
590
+ const open = SqlOpen.encode({ name, migrations, durability: options.durability, backup })
518
591
  const db = new Database(link, workers, name, open)
519
592
  await link.run('read', connection => db.handle(connection))
520
593
  return db
@@ -644,11 +717,21 @@ function doneOf(done: {
644
717
 
645
718
  type Want = 'all' | 'one' | 'scalar'
646
719
 
720
+ /** A column a walk's rows are ordered by, as the rows name it. */
721
+ export interface Ordered {
722
+ column: string
723
+ descending: boolean
724
+ }
725
+
726
+ /** The database's walk of a statement's rows, which its table's `each` reads; a transaction has none. */
727
+ export const walk: unique symbol = Symbol('walk')
728
+
647
729
  /** What reads and writes a database: the database itself, or a transaction of it. */
648
730
  export interface Runner {
649
731
  readonly describe: string
650
732
  rows(statement: Sql, want: Want): Promise<Answered>
651
733
  exec(statement: Sql): Promise<Done>
734
+ [walk]?<T = Row>(statement: Sql, order: readonly Ordered[] | undefined): AsyncGenerator<T>
652
735
  }
653
736
 
654
737
  /** The reads every runner shares: all, one and scalar over its rows. */
@@ -880,19 +963,30 @@ export class Database implements Runner, Home {
880
963
 
881
964
  /**
882
965
  * The rows a statement gives, one at a time as their parts arrive: an
883
- * export that holds one part, not every row. The server reads them from
884
- * one snapshot, at most 64 MiB.
966
+ * export that holds a part, not every row, however many there are. The
967
+ * server reads them a part at a time from one snapshot, which lasts five
968
+ * seconds at most: a walk that takes longer fails `limit`, and is read a
969
+ * page at a time with a table's `list`, or ordered by its key with a
970
+ * table's `each`, which reads on past it.
885
971
  */
886
972
  async *each<T = Row>(...statement: Statement): AsyncGenerator<T> {
973
+ yield* this[walk]<T>(statementOf(statement), undefined)
974
+ }
975
+
976
+ /**
977
+ * A statement's rows as the server reads them, `want: each`; ordered by
978
+ * `order`, a unique column last, the server reads on past one snapshot.
979
+ */
980
+ async *[walk]<T = Row>(piece: Sql, order: readonly Ordered[] | undefined): AsyncGenerator<T> {
887
981
  this.#refuseAround('a read')
888
- const piece = statementOf(statement)
889
982
  const connection = await this.#link.connection()
890
983
  const handle = await this.handle(connection)
891
984
  const body = SqlQuery.encode({
892
985
  handle,
893
986
  text: piece.text,
894
987
  values: [...piece.values],
895
- want: 'all',
988
+ want: 'each',
989
+ order: order === undefined ? undefined : [...order],
896
990
  })
897
991
  const stream = await connection.session.open(methods['sql.query'], body, true)
898
992
  try {
package/src/store.ts CHANGED
@@ -19,6 +19,7 @@ import {
19
19
  type SelfMetrics,
20
20
  sidecar,
21
21
  } from './connection.ts'
22
+ import { type Directory, type DirectoryOptions, openDirectory } from './directory.ts'
22
23
  import { ClosedError, InvalidError } from './errors.ts'
23
24
  import { Instruments } from './instruments.ts'
24
25
  import {
@@ -491,6 +492,17 @@ export class Store implements AsyncDisposable {
491
492
  return openFiles(this.#link, name, options)
492
493
  }
493
494
 
495
+ /**
496
+ * A folder of the store's machine under a name, which the store lists and
497
+ * reads and never writes; over a token, the server's own by its name:
498
+ *
499
+ * const movies = store.directory('movies', { path: 'D:/Movies' })
500
+ * const photos = store.directory('photos', { path: '/mnt/photos', every: '15m', ignore: ['*.part', '.*'] })
501
+ */
502
+ directory(name: string, options?: DirectoryOptions): Directory {
503
+ return openDirectory(this.#link, name, options)
504
+ }
505
+
494
506
  /**
495
507
  * The application's database name, sql/<name>.db, once its migrations
496
508
  * are applied and checked: a migration that fails, or one changed after