@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/dist/sql.d.ts CHANGED
@@ -36,6 +36,14 @@ export interface DatabaseOptions {
36
36
  * with it. A database open already keeps what it was opened with.
37
37
  */
38
38
  durability?: Durability;
39
+ /**
40
+ * Whether backups take the database; `false` keeps its file and the
41
+ * bytes of its files in `local/` rather than `sql/`, where no backup
42
+ * looks, open or not, and no node copies it: each node that opens it
43
+ * writes its own. A name lives in one folder: one whose file lies in the
44
+ * other is InvalidError, naming both.
45
+ */
46
+ backup?: boolean;
39
47
  }
40
48
  /** What a write changed: the rows, and SQLite's rowid of the row it inserted, 0 when none. */
41
49
  export interface Done {
@@ -74,6 +82,13 @@ export declare function joinedWith(pieces: readonly Sql[], joiner: string): Sql;
74
82
  * and parentheses, which would bind with its neighbours'.
75
83
  */
76
84
  export declare function standsAlone(text: string): boolean;
85
+ /**
86
+ * A piece as a query takes it. What the query writes after a piece, an and,
87
+ * a ), a desc or a where, must stay SQL: a piece that ends inside a --
88
+ * comment gets the newline that ends it, and one that ends inside a block
89
+ * comment, which only its closing mark ends, is refused.
90
+ */
91
+ export declare function checked(piece: Sql): Sql;
77
92
  /** Something that writes itself as SQL inside another piece: a table's query. */
78
93
  export interface Embeddable {
79
94
  /** its text and values, wrapped as a subquery is */
@@ -130,11 +145,19 @@ interface Answered {
130
145
  rows: SqlValue[][];
131
146
  }
132
147
  type Want = 'all' | 'one' | 'scalar';
148
+ /** A column a walk's rows are ordered by, as the rows name it. */
149
+ export interface Ordered {
150
+ column: string;
151
+ descending: boolean;
152
+ }
153
+ /** The database's walk of a statement's rows, which its table's `each` reads; a transaction has none. */
154
+ export declare const walk: unique symbol;
133
155
  /** What reads and writes a database: the database itself, or a transaction of it. */
134
156
  export interface Runner {
135
157
  readonly describe: string;
136
158
  rows(statement: Sql, want: Want): Promise<Answered>;
137
159
  exec(statement: Sql): Promise<Done>;
160
+ [walk]?<T = Row>(statement: Sql, order: readonly Ordered[] | undefined): AsyncGenerator<T>;
138
161
  }
139
162
  /** Whether the caller runs inside the function of a database's transaction. */
140
163
  export declare function insideDatabaseTx(): boolean;
@@ -223,10 +246,18 @@ export declare class Database implements Runner, Home {
223
246
  columns<T = Row>(...statement: Statement): Promise<Columns<T>>;
224
247
  /**
225
248
  * The rows a statement gives, one at a time as their parts arrive: an
226
- * export that holds one part, not every row. The server reads them from
227
- * one snapshot, at most 64 MiB.
249
+ * export that holds a part, not every row, however many there are. The
250
+ * server reads them a part at a time from one snapshot, which lasts five
251
+ * seconds at most: a walk that takes longer fails `limit`, and is read a
252
+ * page at a time with a table's `list`, or ordered by its key with a
253
+ * table's `each`, which reads on past it.
228
254
  */
229
255
  each<T = Row>(...statement: Statement): AsyncGenerator<T>;
256
+ /**
257
+ * A statement's rows as the server reads them, `want: each`; ordered by
258
+ * `order`, a unique column last, the server reads on past one snapshot.
259
+ */
260
+ [walk]<T = Row>(piece: Sql, order: readonly Ordered[] | undefined): AsyncGenerator<T>;
230
261
  /**
231
262
  * A table of the database, typed where it opens: its rows' inserts and
232
263
  * upserts, and queries built without SQL text. It costs nothing until its
package/dist/sql.js CHANGED
@@ -40,17 +40,36 @@ export function grouped(text) {
40
40
  if (!text.startsWith('(') || !text.endsWith(')')) {
41
41
  return /^[01]$/.test(text);
42
42
  }
43
+ // A parenthesis inside quotes or a comment counts for nothing: ('(') or ('x') is two groups, not one.
43
44
  let depth = 0;
44
45
  for (let at = 0; at < text.length; at++) {
45
- if (text[at] === '(')
46
+ const c = text[at];
47
+ if (c === "'" || c === '"' || c === '`') {
48
+ at = closing(text, at, c);
49
+ continue;
50
+ }
51
+ if (c === '-' && text[at + 1] === '-') {
52
+ at = text.indexOf('\n', at);
53
+ if (at < 0)
54
+ break;
55
+ continue;
56
+ }
57
+ if (c === '/' && text[at + 1] === '*') {
58
+ at = text.indexOf('*/', at + 2);
59
+ if (at < 0)
60
+ break;
61
+ at++;
62
+ continue;
63
+ }
64
+ if (c === '(')
46
65
  depth++;
47
- if (text[at] === ')')
66
+ if (c === ')')
48
67
  depth--;
49
68
  if (depth === 0 && at < text.length - 1) {
50
69
  return false;
51
70
  }
52
71
  }
53
- return true;
72
+ return depth === 0;
54
73
  }
55
74
  /** Pieces joined with and or or, each in parentheses unless it may stand as it is. */
56
75
  export function joinedWith(pieces, joiner) {
@@ -101,6 +120,54 @@ export function standsAlone(text) {
101
120
  }
102
121
  return true;
103
122
  }
123
+ /**
124
+ * A piece as a query takes it. What the query writes after a piece, an and,
125
+ * a ), a desc or a where, must stay SQL: a piece that ends inside a --
126
+ * comment gets the newline that ends it, and one that ends inside a block
127
+ * comment, which only its closing mark ends, is refused.
128
+ */
129
+ export function checked(piece) {
130
+ switch (commentAtEnd(piece.text)) {
131
+ case 'line':
132
+ return new Sql(`${piece.text}\n`, piece.values, piece.bare);
133
+ case 'block':
134
+ throw new InvalidError(`a piece of SQL ends inside a /* comment, which would hide what the query writes after it: ${piece.text}`);
135
+ }
136
+ return piece;
137
+ }
138
+ /** Text written into another piece, a -- comment at its end ended by a newline. */
139
+ function ended(text) {
140
+ return commentAtEnd(text) === 'line' ? `${text}\n` : text;
141
+ }
142
+ /**
143
+ * The comment text ends inside, outside quotes and brackets, if it ends
144
+ * inside one: `a = 1 -- why` ends inside a line comment.
145
+ */
146
+ function commentAtEnd(text) {
147
+ for (let at = 0; at < text.length; at++) {
148
+ const c = text[at];
149
+ if (c === "'" || c === '"' || c === '`') {
150
+ at = closing(text, at, c);
151
+ }
152
+ else if (c === '[') {
153
+ at = text.indexOf(']', at + 1);
154
+ if (at < 0)
155
+ return undefined;
156
+ }
157
+ else if (c === '-' && text[at + 1] === '-') {
158
+ at = text.indexOf('\n', at);
159
+ if (at < 0)
160
+ return 'line';
161
+ }
162
+ else if (c === '/' && text[at + 1] === '*') {
163
+ at = text.indexOf('*/', at + 2);
164
+ if (at < 0)
165
+ return 'block';
166
+ at++;
167
+ }
168
+ }
169
+ return undefined;
170
+ }
104
171
  function isEmbeddable(value) {
105
172
  return (typeof value === 'object' &&
106
173
  value !== null &&
@@ -122,7 +189,7 @@ function piece(first, values) {
122
189
  const out = [];
123
190
  values.forEach((value, at) => {
124
191
  if (value instanceof Sql) {
125
- text += value.text;
192
+ text += ended(value.text);
126
193
  out.push(...value.values);
127
194
  }
128
195
  else if (isEmbeddable(value)) {
@@ -162,7 +229,7 @@ function listed(value) {
162
229
  return value;
163
230
  }
164
231
  function group(conditions, joiner, empty) {
165
- const pieces = conditions.map(conditionOf);
232
+ const pieces = conditions.map(condition => checked(conditionOf(condition)));
166
233
  if (pieces.length === 0) {
167
234
  return new Sql(empty, []);
168
235
  }
@@ -278,7 +345,7 @@ export function placeholders(text) {
278
345
  }
279
346
  return { positional, named, numbered };
280
347
  }
281
- /** The index past a quoted run that starts at `at`, a doubled quote inside it kept. */
348
+ /** The index of the quote that ends a quoted run starting at `at`, a doubled quote inside it kept. */
282
349
  function closing(text, at, quote) {
283
350
  for (let next = at + 1; next < text.length; next++) {
284
351
  if (text[next] === quote) {
@@ -348,7 +415,8 @@ export async function openDatabase(link, workers, name, options = {}) {
348
415
  checkName(name, 'database');
349
416
  checkDurability(options.durability, `sql ${name}`);
350
417
  const migrations = options.migrations === undefined ? undefined : await migrationFiles(options.migrations);
351
- const open = SqlOpen.encode({ name, migrations, durability: options.durability });
418
+ const backup = options.backup === false ? false : undefined;
419
+ const open = SqlOpen.encode({ name, migrations, durability: options.durability, backup });
352
420
  const db = new Database(link, workers, name, open);
353
421
  await link.run('read', connection => db.handle(connection));
354
422
  return db;
@@ -456,6 +524,8 @@ function doneOf(done) {
456
524
  const exact = rowid >= BigInt(Number.MIN_SAFE_INTEGER) && rowid <= BigInt(Number.MAX_SAFE_INTEGER);
457
525
  return { changes: done.changes ?? 0, lastInsertRowid: exact ? Number(rowid) : rowid };
458
526
  }
527
+ /** The database's walk of a statement's rows, which its table's `each` reads; a transaction has none. */
528
+ export const walk = Symbol('walk');
459
529
  /** The reads every runner shares: all, one and scalar over its rows. */
460
530
  async function all(runner, statement) {
461
531
  const answered = await runner.rows(statement, 'all');
@@ -623,19 +693,29 @@ export class Database {
623
693
  }
624
694
  /**
625
695
  * The rows a statement gives, one at a time as their parts arrive: an
626
- * export that holds one part, not every row. The server reads them from
627
- * one snapshot, at most 64 MiB.
696
+ * export that holds a part, not every row, however many there are. The
697
+ * server reads them a part at a time from one snapshot, which lasts five
698
+ * seconds at most: a walk that takes longer fails `limit`, and is read a
699
+ * page at a time with a table's `list`, or ordered by its key with a
700
+ * table's `each`, which reads on past it.
628
701
  */
629
702
  async *each(...statement) {
703
+ yield* this[walk](statementOf(statement), undefined);
704
+ }
705
+ /**
706
+ * A statement's rows as the server reads them, `want: each`; ordered by
707
+ * `order`, a unique column last, the server reads on past one snapshot.
708
+ */
709
+ async *[walk](piece, order) {
630
710
  this.#refuseAround('a read');
631
- const piece = statementOf(statement);
632
711
  const connection = await this.#link.connection();
633
712
  const handle = await this.handle(connection);
634
713
  const body = SqlQuery.encode({
635
714
  handle,
636
715
  text: piece.text,
637
716
  values: [...piece.values],
638
- want: 'all',
717
+ want: 'each',
718
+ order: order === undefined ? undefined : [...order],
639
719
  });
640
720
  const stream = await connection.session.open(methods['sql.query'], body, true);
641
721
  try {
package/dist/store.d.ts CHANGED
@@ -4,6 +4,7 @@ import { Channel } from './channels.ts';
4
4
  import { Clock } from './clock.ts';
5
5
  import { Config, type ConfigOptions, type Layer, type Value } from './config.ts';
6
6
  import { type Durability, Link, type SelfMetrics } from './connection.ts';
7
+ import { type Directory, type DirectoryOptions } from './directory.ts';
7
8
  import { type Queue, type QueueOptions, type Run, type Schedule, type ScheduleOptions, type ScheduleWhen } from './jobs.ts';
8
9
  import { Bucket, type BucketOptions, Counters, type CountersOptions } from './kv.ts';
9
10
  import { Quota, type Rate, RateLimit, type RateLimitOptions } from './limits.ts';
@@ -306,6 +307,14 @@ export declare class Store implements AsyncDisposable {
306
307
  * const reports = store.files('reports', { ttl: '24h', maxFileSize: '2GiB' })
307
308
  */
308
309
  files(name: string, options?: FilesOptions): Files;
310
+ /**
311
+ * A folder of the store's machine under a name, which the store lists and
312
+ * reads and never writes; over a token, the server's own by its name:
313
+ *
314
+ * const movies = store.directory('movies', { path: 'D:/Movies' })
315
+ * const photos = store.directory('photos', { path: '/mnt/photos', every: '15m', ignore: ['*.part', '.*'] })
316
+ */
317
+ directory(name: string, options?: DirectoryOptions): Directory;
309
318
  /**
310
319
  * The application's database name, sql/<name>.db, once its migrations
311
320
  * are applied and checked: a migration that fails, or one changed after
package/dist/store.js CHANGED
@@ -7,6 +7,7 @@ import { Channel } from './channels.js';
7
7
  import { Clock } from './clock.js';
8
8
  import { Config } from './config.js';
9
9
  import { asking, checkDurability, checkMaxSeries, embedded, Link, privateChild, remote, sidecar, } from './connection.js';
10
+ import { openDirectory } from './directory.js';
10
11
  import { ClosedError, InvalidError } from './errors.js';
11
12
  import { Instruments } from './instruments.js';
12
13
  import { openQueue, openSchedule, } from './jobs.js';
@@ -247,6 +248,16 @@ export class Store {
247
248
  files(name, options) {
248
249
  return openFiles(this.#link, name, options);
249
250
  }
251
+ /**
252
+ * A folder of the store's machine under a name, which the store lists and
253
+ * reads and never writes; over a token, the server's own by its name:
254
+ *
255
+ * const movies = store.directory('movies', { path: 'D:/Movies' })
256
+ * const photos = store.directory('photos', { path: '/mnt/photos', every: '15m', ignore: ['*.part', '.*'] })
257
+ */
258
+ directory(name, options) {
259
+ return openDirectory(this.#link, name, options);
260
+ }
250
261
  /**
251
262
  * The application's database name, sql/<name>.db, once its migrations
252
263
  * are applied and checked: a migration that fails, or one changed after