@tinyshed/tinystore 0.7.0 → 0.8.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.
@@ -3233,8 +3233,9 @@ export const JobsJob = message('jobs.Job', {
3233
3233
  });
3234
3234
  /**
3235
3235
  * A page of a queue's jobs: those whose ids start with a prefix, in the byte
3236
- * order of their ids, or with no prefix and the failed state, the last failed
3237
- * first.
3236
+ * order of their ids; with no prefix every job, those with ids first, then
3237
+ * those without as they run, then those without that failed, the last failed
3238
+ * first; with no prefix and the failed state the failed alone, the last first.
3238
3239
  */
3239
3240
  export const JobsList = message('jobs.List', {
3240
3241
  handle: [1, uint],
@@ -9776,6 +9777,8 @@ export const SearchQuery = message('search.Query', {
9776
9777
  prefixEvery: [10, bool],
9777
9778
  /** utf8, utf16 or chars: each hit says where it matched, counted in that unit */
9778
9779
  matches: [11, str],
9780
+ /** the least cosine a document's vector has for the vector to find it */
9781
+ minSimilarity: [12, float],
9779
9782
  }, {
9780
9783
  write(w, v) {
9781
9784
  const head = w.openMap();
@@ -9835,6 +9838,11 @@ export const SearchQuery = message('search.Query', {
9835
9838
  w.str(v.matches);
9836
9839
  n++;
9837
9840
  }
9841
+ if (v.minSimilarity !== undefined) {
9842
+ w.field(12);
9843
+ w.float(v.minSimilarity);
9844
+ n++;
9845
+ }
9838
9846
  w.closeMap(head, n);
9839
9847
  },
9840
9848
  read(r) {
@@ -9849,6 +9857,7 @@ export const SearchQuery = message('search.Query', {
9849
9857
  let $prefix;
9850
9858
  let $prefixEvery;
9851
9859
  let $matches;
9860
+ let $minSimilarity;
9852
9861
  for (let n = r.message(); n > 0; n--) {
9853
9862
  switch (r.field()) {
9854
9863
  case 1:
@@ -9884,6 +9893,9 @@ export const SearchQuery = message('search.Query', {
9884
9893
  case 11:
9885
9894
  $matches = r.str();
9886
9895
  break;
9896
+ case 12:
9897
+ $minSimilarity = r.float();
9898
+ break;
9887
9899
  default:
9888
9900
  r.skip();
9889
9901
  }
@@ -9901,6 +9913,7 @@ export const SearchQuery = message('search.Query', {
9901
9913
  prefix: $prefix,
9902
9914
  prefixEvery: $prefixEvery,
9903
9915
  matches: $matches,
9916
+ minSimilarity: $minSimilarity,
9904
9917
  };
9905
9918
  },
9906
9919
  });
@@ -11589,8 +11602,8 @@ export const SearchSetMany = message('search.SetMany', {
11589
11602
  });
11590
11603
  /**
11591
11604
  * A hit: a document and its value, or a table's row, a value a column of
11592
- * the answer's columns, as sql.Rows holds one, and where the search's words
11593
- * matched it when the query asked.
11605
+ * the answer's columns, as sql.Rows holds one, where the search's words
11606
+ * matched it when the query asked, and what each half of the search gave it.
11594
11607
  */
11595
11608
  export const SearchHit = message('search.Hit', {
11596
11609
  id: [1, str],
@@ -11599,6 +11612,10 @@ export const SearchHit = message('search.Hit', {
11599
11612
  score: [3, float],
11600
11613
  row: [4, list(sqlValue)],
11601
11614
  matches: [5, list(SearchMatch)],
11615
+ /** its words' score, where they found it among their best */
11616
+ textScore: [6, float],
11617
+ /** its vector's cosine with the search's, where both have one */
11618
+ similarity: [7, float],
11602
11619
  }, {
11603
11620
  write(w, v) {
11604
11621
  const head = w.openMap();
@@ -11634,6 +11651,16 @@ export const SearchHit = message('search.Hit', {
11634
11651
  }
11635
11652
  n++;
11636
11653
  }
11654
+ if (v.textScore !== undefined) {
11655
+ w.field(6);
11656
+ w.float(v.textScore);
11657
+ n++;
11658
+ }
11659
+ if (v.similarity !== undefined) {
11660
+ w.field(7);
11661
+ w.float(v.similarity);
11662
+ n++;
11663
+ }
11637
11664
  w.closeMap(head, n);
11638
11665
  },
11639
11666
  read(r) {
@@ -11642,6 +11669,8 @@ export const SearchHit = message('search.Hit', {
11642
11669
  let $score;
11643
11670
  let $row;
11644
11671
  let $matches;
11672
+ let $textScore;
11673
+ let $similarity;
11645
11674
  for (let n = r.message(); n > 0; n--) {
11646
11675
  switch (r.field()) {
11647
11676
  case 1:
@@ -11671,12 +11700,26 @@ export const SearchHit = message('search.Hit', {
11671
11700
  $matches = items0;
11672
11701
  break;
11673
11702
  }
11703
+ case 6:
11704
+ $textScore = r.float();
11705
+ break;
11706
+ case 7:
11707
+ $similarity = r.float();
11708
+ break;
11674
11709
  default:
11675
11710
  r.skip();
11676
11711
  }
11677
11712
  }
11678
11713
  r.leave();
11679
- return { id: $id, value: $value, score: $score, row: $row, matches: $matches };
11714
+ return {
11715
+ id: $id,
11716
+ value: $value,
11717
+ score: $score,
11718
+ row: $row,
11719
+ matches: $matches,
11720
+ textScore: $textScore,
11721
+ similarity: $similarity,
11722
+ };
11680
11723
  },
11681
11724
  });
11682
11725
  export const SearchFound = message('search.Found', {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyshed/tinystore",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
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
  "homepage": "https://tinyshed.org/tinystore",
@@ -31,12 +31,12 @@
31
31
  "README.md"
32
32
  ],
33
33
  "optionalDependencies": {
34
- "@tinyshed/tinystore-linux-x64": "0.7.0",
35
- "@tinyshed/tinystore-linux-arm64": "0.7.0",
36
- "@tinyshed/tinystore-linux-x64-musl": "0.7.0",
37
- "@tinyshed/tinystore-linux-arm64-musl": "0.7.0",
38
- "@tinyshed/tinystore-darwin-arm64": "0.7.0",
39
- "@tinyshed/tinystore-darwin-x64": "0.7.0",
40
- "@tinyshed/tinystore-win32-x64": "0.7.0"
34
+ "@tinyshed/tinystore-linux-x64": "0.8.0",
35
+ "@tinyshed/tinystore-linux-arm64": "0.8.0",
36
+ "@tinyshed/tinystore-linux-x64-musl": "0.8.0",
37
+ "@tinyshed/tinystore-linux-arm64-musl": "0.8.0",
38
+ "@tinyshed/tinystore-darwin-arm64": "0.8.0",
39
+ "@tinyshed/tinystore-darwin-x64": "0.8.0",
40
+ "@tinyshed/tinystore-win32-x64": "0.8.0"
41
41
  }
42
42
  }
package/src/console.ts CHANGED
@@ -81,9 +81,12 @@ const cyan = '\x1b[36m'
81
81
  /**
82
82
  * A line as a person reads it: the time of day, the level padded to five, the
83
83
  * stream, the message, the context's fields and the attributes', and the
84
- * trace's first eight digits. A value of several lines, a stack or a
85
- * traceback, follows the line, indented. A key or a string shows without its
86
- * quotes when it is one word with no '=', quote or backslash.
84
+ * trace's first eight digits. A message's further lines, and then a value of
85
+ * several lines, a stack or a traceback, follow the line, indented, so that
86
+ * none of them starts where a line does. A key or a string shows without its
87
+ * quotes when it is one word with no '=', quote or backslash. What a program
88
+ * logged shows no control character but a tab: the message, the event's name,
89
+ * a value below the line and a source each show it as its escape.
87
90
  */
88
91
  export function prettyLine(line: ConsoleLine, look: Look): string {
89
92
  const paint = (hue: string, text: string) => (look.color ? hue + text + reset : text)
@@ -96,7 +99,7 @@ export function prettyLine(line: ConsoleLine, look: Look): string {
96
99
  out += `${separator}${paint(cyan, line.stream)}`
97
100
  separator = ' '
98
101
  }
99
- const message = prettyMessage(line)
102
+ const [message, further] = prettyMessage(line)
100
103
  if (message !== '') {
101
104
  out += `${separator}${message}`
102
105
  separator = ' '
@@ -119,18 +122,48 @@ export function prettyLine(line: ConsoleLine, look: Look): string {
119
122
  if (line.traceId !== undefined) {
120
123
  field('trace', line.traceId.slice(0, 8))
121
124
  }
125
+ for (const part of further) {
126
+ out += `\n ${escaped(part)}`
127
+ }
122
128
  for (const [key, text] of below) {
123
- text
124
- .replace(/[\r\n]+$/, '')
125
- .split('\n')
126
- .forEach((part, i) => {
127
- const shown = part.replace(/\r$/, '')
128
- out += `\n ${paint(dim, i === 0 ? `${key}: ${shown}` : shown)}`
129
- })
129
+ linesOf(text).forEach((part, i) => {
130
+ out += `\n ${paint(dim, escaped(i === 0 ? `${key}: ${part}` : part))}`
131
+ })
130
132
  }
131
133
  return `${out}\n`
132
134
  }
133
135
 
136
+ /**
137
+ * The lines of a text of several, without the line ends after the last, and
138
+ * each without the carriage return before its newline: "line one\r\nline
139
+ * two\r\n" is line one, line two.
140
+ */
141
+ function linesOf(text: string): string[] {
142
+ const lines = text.replace(/[\r\n]+$/, '').split('\n')
143
+ return lines.map(part => part.replace(/\r$/, ''))
144
+ }
145
+
146
+ /**
147
+ * Text a program logged as a pretty line shows it: each control character but
148
+ * a tab, and DEL, as its JSON escape, so that none reaches the terminal as an
149
+ * escape sequence, a carriage return or a line of its own. The colours the
150
+ * console paints with are its own, never in this text.
151
+ *
152
+ * "\x1b[2J" → \u001b[2J "a\rb" → a\rb "\x7f" → \u007f
153
+ */
154
+ function escaped(text: string): string {
155
+ let out = ''
156
+ for (const c of text) {
157
+ const code = c.codePointAt(0) as number
158
+ if ((code < 0x20 && c !== '\t') || code === 0x7f) {
159
+ out += code === 0x7f ? '\\u007f' : JSON.stringify(c).slice(1, -1)
160
+ } else {
161
+ out += c
162
+ }
163
+ }
164
+ return out
165
+ }
166
+
134
167
  /** A level as slog spells it: INFO, WARN+2, DEBUG-4. */
135
168
  export function levelLabel(level: number): string {
136
169
  const spell = (base: string, from: number) => {
@@ -157,12 +190,19 @@ function prettyLevel(level: number | undefined): [string, string] {
157
190
  return [levelLabel(level), hue]
158
191
  }
159
192
 
160
- function prettyMessage(line: ConsoleLine): string {
161
- const body = line.msg ?? ''
193
+ /**
194
+ * A log line's message, or an event's name and the message it may carry, as
195
+ * the line shows them; and the further lines of a message of several, which
196
+ * go below the line as a value's do.
197
+ */
198
+ function prettyMessage(line: ConsoleLine): [string, string[]] {
199
+ const [first, ...further] = linesOf(line.msg ?? '')
200
+ const body = escaped(first ?? '')
162
201
  if (line.event === undefined) {
163
- return body
202
+ return [body, further]
164
203
  }
165
- return body === '' ? line.event : `${line.event} ${body}`
204
+ const event = escaped(line.event)
205
+ return [body === '' ? event : `${event} ${body}`, further]
166
206
  }
167
207
 
168
208
  /** How a field's JSON shows, and whether it is text of several lines, which goes under the line. */
@@ -247,7 +287,7 @@ function shortSource(json: string): string | undefined {
247
287
  }
248
288
  const parts = source.file.split(/[\\/]+/).filter(part => part !== '')
249
289
  const line = typeof source.line === 'number' ? source.line : 0
250
- return `${parts.slice(-2).join('/')}:${line}`
290
+ return escaped(`${parts.slice(-2).join('/')}:${line}`)
251
291
  }
252
292
 
253
293
  /** The names `redact` takes to hide the usual secrets, as Go's console.Secrets and Python's SECRETS. */
package/src/jobs.ts CHANGED
@@ -639,9 +639,10 @@ export class Queue<T> {
639
639
  }
640
640
 
641
641
  /**
642
- * Changes the id's job when it has not started: its value, and its time,
643
- * group or repeat when the options give them. It says whether it did: a
644
- * job that runs, ran or never was answers false.
642
+ * Changes the id's job when it is not running: its value, the steps kept
643
+ * for the old one dropped with it, and its time, group or repeat when the
644
+ * options give them. It says whether it did: a job that runs, is done or
645
+ * failed, or never was answers false.
645
646
  */
646
647
  async update(id: string, value: T, options: JobOptions = {}): Promise<boolean> {
647
648
  const fields = { ...jobFields(options), id, value: this.#source.values.encode(value) }
@@ -679,7 +680,10 @@ export class Queue<T> {
679
680
  return watchJob(this.#source, id)
680
681
  }
681
682
 
682
- /** A page of the queue's jobs whose ids start with a prefix, or of its failed ones. */
683
+ /**
684
+ * A page of the queue's jobs: with no prefix every job, those with ids by id,
685
+ * then those without as they run, then those without that failed.
686
+ */
683
687
  async list(options: ListOptions = {}): Promise<JobPage<T>> {
684
688
  const body = await callOf(
685
689
  this.#source,
@@ -871,7 +875,7 @@ export class StoreTxQueue<T> {
871
875
  this.#write('jobs.set', { ...jobFields(options), id }, value)
872
876
  }
873
877
 
874
- /** Changes the id's job when it has not started, with the commit. */
878
+ /** Changes the id's job when it is not running, its old value's steps dropped, with the commit. */
875
879
  async update(id: string, value: T, options: JobOptions = {}): Promise<void> {
876
880
  this.#write('jobs.update', { ...jobFields(options), id }, value)
877
881
  }
package/src/locks.ts CHANGED
@@ -96,6 +96,7 @@ export class Semaphore {
96
96
  if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1000) {
97
97
  throw new InvalidError(`semaphore ${name}: a limit of ${options.limit}, not 1 to 1000`)
98
98
  }
99
+ keepLimit(link, name, options.limit)
99
100
  this.name = name
100
101
  this.limit = options.limit
101
102
  this.#keys = new Keys(link, 'semaphore', name, options.limit, options)
@@ -114,6 +115,27 @@ export class Semaphore {
114
115
  }
115
116
  }
116
117
 
118
+ // The limit each semaphore's first open gave, by the link of the store that
119
+ // opened it: one name keeps one limit in a program, and two stores are two
120
+ // programs, each of whose holds the store admits by its own limit.
121
+ const opened = new WeakMap<Link, Map<string, number>>()
122
+
123
+ /** Keeps the limit a semaphore's first open on this store gives: another limit is refused, naming both. */
124
+ function keepLimit(link: Link, name: string, limit: number): void {
125
+ let limits = opened.get(link)
126
+ if (limits === undefined) {
127
+ limits = new Map()
128
+ opened.set(link, limits)
129
+ }
130
+ const first = limits.get(name) ?? limit
131
+ if (first !== limit) {
132
+ throw new InvalidError(
133
+ `semaphore ${name}: open in this program with a limit of ${first}, not ${limit}`,
134
+ )
135
+ }
136
+ limits.set(name, first)
137
+ }
138
+
117
139
  function waitOf(options: HoldOptions | undefined): number {
118
140
  return ms(options?.wait ?? defaultWait)
119
141
  }
package/src/query.ts CHANGED
@@ -8,6 +8,7 @@ import { check, type StandardSchemaV1 } from './schema.ts'
8
8
  import {
9
9
  type Condition,
10
10
  cellOf,
11
+ checked,
11
12
  conditionOf,
12
13
  type Done,
13
14
  type Embeddable,
@@ -120,7 +121,7 @@ export class Query<T = Row> implements Embeddable {
120
121
 
121
122
  /** The columns a row holds, as SQL text, and the shape of the row they make. */
122
123
  select<R = Row>(columns: string | Sql): Query<R> {
123
- const select = typeof columns === 'string' ? new Sql(columns, []) : columns
124
+ const select = checked(typeof columns === 'string' ? new Sql(columns, []) : columns)
124
125
  return new Query<R>(this.#source, { ...this.#parts, select })
125
126
  }
126
127
 
@@ -193,7 +194,7 @@ export class Query<T = Row> implements Embeddable {
193
194
  }
194
195
  const order =
195
196
  column instanceof Sql
196
- ? { piece: column, direction }
197
+ ? { piece: checked(column), direction }
197
198
  : { piece: new Sql(identOf(column), []), column, direction }
198
199
  return this.#with({ order: [...this.#parts.order, order] })
199
200
  }
@@ -285,9 +286,16 @@ export class Query<T = Row> implements Embeddable {
285
286
  'a page is read by the query order, of columns by their names: orderBy(…) first',
286
287
  )
287
288
  }
289
+ // A page reads its limit's rows after its cursor: the query's own limit or
290
+ // offset would be dropped, and limit(100) page through every row.
291
+ if (this.#parts.limit !== undefined || this.#parts.offset !== undefined) {
292
+ throw new InvalidError(
293
+ 'list after a limit or an offset: list pages the rows itself and takes its own limit',
294
+ )
295
+ }
288
296
  const limit = whole(options.limit ?? 100, 'a page limit')
289
- const digest = digestOf(render({ ...this.#parts, limit: undefined, offset: undefined }))
290
- let parts: Parts = { ...this.#parts, limit, offset: undefined }
297
+ const digest = digestOf(render(this.#parts))
298
+ let parts: Parts = { ...this.#parts, limit }
291
299
  if (options.after !== undefined) {
292
300
  const after = cursorOf(options.after, digest)
293
301
  parts = {
@@ -337,8 +345,9 @@ export class Query<T = Row> implements Embeddable {
337
345
  for (const name of names) {
338
346
  const value = values[name]
339
347
  if (value instanceof Sql) {
340
- sets.push(`${identOf(name)} = ${value.text}`)
341
- out.push(...value.values)
348
+ const set = checked(value)
349
+ sets.push(`${identOf(name)} = ${set.text}`)
350
+ out.push(...set.values)
342
351
  } else {
343
352
  sets.push(`${identOf(name)} = ?`)
344
353
  out.push(fieldOf(value, name, this.#source.types))
@@ -399,7 +408,7 @@ export class Query<T = Row> implements Embeddable {
399
408
  }
400
409
 
401
410
  #joined(kind: string, table: string, on: string | Sql): Query<T> {
402
- const condition = typeof on === 'string' ? new Sql(on, []) : on
411
+ const condition = checked(typeof on === 'string' ? new Sql(on, []) : on)
403
412
  const ref = tableRef(table)
404
413
  const join = new Sql(`${kind} ${ref.text} on ${condition.text}`, condition.values)
405
414
  return this.#with({ joins: [...this.#parts.joins, join] })
@@ -414,6 +423,22 @@ export class Query<T = Row> implements Embeddable {
414
423
  if (this.#parts.joins.length > 0) {
415
424
  throw new InvalidError(`${what} of a join: write it in SQL`)
416
425
  }
426
+ // SQLite's update and delete take none of these: limit(10).delete()
427
+ // would delete every row the conditions match.
428
+ const parts = this.#parts
429
+ const shaped =
430
+ parts.limit !== undefined ||
431
+ parts.offset !== undefined ||
432
+ parts.order.length > 0 ||
433
+ parts.groups.length > 0 ||
434
+ parts.having.length > 0 ||
435
+ parts.select !== undefined ||
436
+ parts.includes.length > 0
437
+ if (shaped) {
438
+ throw new InvalidError(
439
+ `${what} with a limit, offset, order, group, select or include: narrow it by conditions, or write it in SQL`,
440
+ )
441
+ }
417
442
  }
418
443
  }
419
444
 
@@ -484,7 +509,7 @@ export class Table<T = Row> extends Query<T> {
484
509
  const values = [...insert.values]
485
510
  if (options.where !== undefined) {
486
511
  // in an upsert's update, a column is the row's that holds the key
487
- const where = conditionOf(options.where)
512
+ const where = checked(conditionOf(options.where))
488
513
  text += ` where ${where.text}`
489
514
  values.push(...where.values)
490
515
  }
@@ -786,21 +811,18 @@ function kept(condition: Condition | string, values: unknown[]): Kept[] {
786
811
  `${counted.positional} placeholders and ${values.length} values: each ? takes one value`,
787
812
  )
788
813
  }
789
- return [
790
- {
791
- piece: new Sql(
792
- condition,
793
- values.map((value, at) => cellOf(value, `value ${at + 1}`)),
794
- ),
795
- bare: false,
796
- },
797
- ]
814
+ const piece = new Sql(
815
+ condition,
816
+ values.map((value, at) => cellOf(value, `value ${at + 1}`)),
817
+ )
818
+ return [{ piece: checked(piece), bare: false }]
798
819
  }
799
820
  if (values.length > 0) {
800
821
  throw new InvalidError('a condition that is not text carries its values: pass it alone')
801
822
  }
802
823
  if (condition instanceof Sql) {
803
- return [{ piece: condition, bare: condition.bare || grouped(condition.text) }]
824
+ const piece = checked(condition)
825
+ return [{ piece, bare: piece.bare || grouped(piece.text) }]
804
826
  }
805
827
  return Object.keys(condition)
806
828
  .sort()
package/src/search.ts CHANGED
@@ -94,6 +94,13 @@ export interface Query {
94
94
  where?: Where | undefined
95
95
  /** this search's way of combining its words and its vector, in place of the index's */
96
96
  hybrid?: { vectorWeight?: number | undefined; rerank?: boolean | undefined } | undefined
97
+ /**
98
+ * the least cosine, from -1 to 1, a document's vector has with the
99
+ * search's for the vector to find it: a search by its vector alone leaves
100
+ * out the hits under it, and one by words too adds nothing for them to
101
+ * the sum; invalid beside a rerank
102
+ */
103
+ minSimilarity?: number | undefined
97
104
  /**
98
105
  * the last word read as the start of a word too, as a search box types:
99
106
  * `crypt` finds `cryptography` as well, at half its field's weight; a
@@ -137,6 +144,10 @@ export interface Hit<T> {
137
144
  score: number
138
145
  /** where the search's words matched it, when the search asked with `matches` */
139
146
  matches?: Match[]
147
+ /** the score its words gave it, as a search by its words alone scores it, where they found it among their best */
148
+ textScore?: number
149
+ /** the cosine of its vector with the search's, from -1 to 1, where both have one */
150
+ similarity?: number
140
151
  }
141
152
 
142
153
  /** What a search found, the best first, and the text it read in fact when a word was misspelt. */
@@ -230,6 +241,7 @@ abstract class Searchable<T> {
230
241
  vector,
231
242
  vectorWeight: asked.hybrid?.vectorWeight,
232
243
  rerank: asked.hybrid?.rerank,
244
+ minSimilarity: asked.minSimilarity,
233
245
  prefix: asked.prefix === true || undefined,
234
246
  // none unless asked, so that a server before it reads the search
235
247
  prefixEvery: asked.prefix === 'every' || undefined,
@@ -251,6 +263,12 @@ abstract class Searchable<T> {
251
263
  if (hit.matches !== undefined) {
252
264
  read.matches = hit.matches.map(matchOf)
253
265
  }
266
+ if (hit.textScore !== undefined) {
267
+ read.textScore = hit.textScore
268
+ }
269
+ if (hit.similarity !== undefined) {
270
+ read.similarity = hit.similarity
271
+ }
254
272
  return read
255
273
  })
256
274
  return found.corrected === undefined ? { hits } : { hits, corrected: found.corrected }
package/src/sql.ts CHANGED
@@ -133,15 +133,32 @@ export function grouped(text: string): boolean {
133
133
  if (!text.startsWith('(') || !text.endsWith(')')) {
134
134
  return /^[01]$/.test(text)
135
135
  }
136
+ // A parenthesis inside quotes or a comment counts for nothing: ('(') or ('x') is two groups, not one.
136
137
  let depth = 0
137
138
  for (let at = 0; at < text.length; at++) {
138
- if (text[at] === '(') depth++
139
- if (text[at] === ')') depth--
139
+ const c = text[at]!
140
+ if (c === "'" || c === '"' || c === '`') {
141
+ at = closing(text, at, c)
142
+ continue
143
+ }
144
+ if (c === '-' && text[at + 1] === '-') {
145
+ at = text.indexOf('\n', at)
146
+ if (at < 0) break
147
+ continue
148
+ }
149
+ if (c === '/' && text[at + 1] === '*') {
150
+ at = text.indexOf('*/', at + 2)
151
+ if (at < 0) break
152
+ at++
153
+ continue
154
+ }
155
+ if (c === '(') depth++
156
+ if (c === ')') depth--
140
157
  if (depth === 0 && at < text.length - 1) {
141
158
  return false
142
159
  }
143
160
  }
144
- return true
161
+ return depth === 0
145
162
  }
146
163
 
147
164
  /** Pieces joined with and or or, each in parentheses unless it may stand as it is. */
@@ -193,6 +210,53 @@ export function standsAlone(text: string): boolean {
193
210
  return true
194
211
  }
195
212
 
213
+ /**
214
+ * A piece as a query takes it. What the query writes after a piece, an and,
215
+ * a ), a desc or a where, must stay SQL: a piece that ends inside a --
216
+ * comment gets the newline that ends it, and one that ends inside a block
217
+ * comment, which only its closing mark ends, is refused.
218
+ */
219
+ export function checked(piece: Sql): Sql {
220
+ switch (commentAtEnd(piece.text)) {
221
+ case 'line':
222
+ return new Sql(`${piece.text}\n`, piece.values, piece.bare)
223
+ case 'block':
224
+ throw new InvalidError(
225
+ `a piece of SQL ends inside a /* comment, which would hide what the query writes after it: ${piece.text}`,
226
+ )
227
+ }
228
+ return piece
229
+ }
230
+
231
+ /** Text written into another piece, a -- comment at its end ended by a newline. */
232
+ function ended(text: string): string {
233
+ return commentAtEnd(text) === 'line' ? `${text}\n` : text
234
+ }
235
+
236
+ /**
237
+ * The comment text ends inside, outside quotes and brackets, if it ends
238
+ * inside one: `a = 1 -- why` ends inside a line comment.
239
+ */
240
+ function commentAtEnd(text: string): 'line' | 'block' | undefined {
241
+ for (let at = 0; at < text.length; at++) {
242
+ const c = text[at]!
243
+ if (c === "'" || c === '"' || c === '`') {
244
+ at = closing(text, at, c)
245
+ } else if (c === '[') {
246
+ at = text.indexOf(']', at + 1)
247
+ if (at < 0) return undefined
248
+ } else if (c === '-' && text[at + 1] === '-') {
249
+ at = text.indexOf('\n', at)
250
+ if (at < 0) return 'line'
251
+ } else if (c === '/' && text[at + 1] === '*') {
252
+ at = text.indexOf('*/', at + 2)
253
+ if (at < 0) return 'block'
254
+ at++
255
+ }
256
+ }
257
+ return undefined
258
+ }
259
+
196
260
  /** Something that writes itself as SQL inside another piece: a table's query. */
197
261
  export interface Embeddable {
198
262
  /** its text and values, wrapped as a subquery is */
@@ -228,7 +292,7 @@ function piece(first: TemplateStringsArray | string, values: unknown[]): Sql {
228
292
  const out: SqlArg[] = []
229
293
  values.forEach((value, at) => {
230
294
  if (value instanceof Sql) {
231
- text += value.text
295
+ text += ended(value.text)
232
296
  out.push(...value.values)
233
297
  } else if (isEmbeddable(value)) {
234
298
  const inner = value.embedded()
@@ -298,7 +362,7 @@ function listed(value: unknown): unknown {
298
362
  }
299
363
 
300
364
  function group(conditions: Condition[], joiner: 'or' | 'and', empty: string): Sql {
301
- const pieces = conditions.map(conditionOf)
365
+ const pieces = conditions.map(condition => checked(conditionOf(condition)))
302
366
  if (pieces.length === 0) {
303
367
  return new Sql(empty, [])
304
368
  }
@@ -423,7 +487,7 @@ export function placeholders(text: string): {
423
487
  return { positional, named, numbered }
424
488
  }
425
489
 
426
- /** The index past a quoted run that starts at `at`, a doubled quote inside it kept. */
490
+ /** The index of the quote that ends a quoted run starting at `at`, a doubled quote inside it kept. */
427
491
  function closing(text: string, at: number, quote: string): number {
428
492
  for (let next = at + 1; next < text.length; next++) {
429
493
  if (text[next] === quote) {