@tinyshed/tinystore 0.4.0 → 0.5.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/errors.d.ts CHANGED
@@ -37,9 +37,10 @@ export declare class InvalidError extends TinystoreError {
37
37
  constructor(message: string, what?: What);
38
38
  }
39
39
  /**
40
- * A bound: memory, size or count. Later, or smaller, it may go through. A
41
- * limit the store names says which, what the call would have taken of it,
42
- * and the bound: `decoded samples`, 120000, 100000.
40
+ * A bound: memory, size or count. Later, or smaller, it may go through. The
41
+ * error names the bound, what the call would have taken of it, and the
42
+ * bound: `set_many documents`, 1001, 1000. `limits` holds the bounds a call
43
+ * meets by those names.
43
44
  */
44
45
  export declare class LimitError extends TinystoreError {
45
46
  readonly limit: string | undefined;
@@ -47,29 +48,87 @@ export declare class LimitError extends TinystoreError {
47
48
  readonly bound: number | undefined;
48
49
  constructor(message: string, what?: What);
49
50
  }
51
+ /** A bound one call meets: its name, as a LimitError's `limit` says it, and the most it takes. */
52
+ export interface Limit {
53
+ readonly name: string;
54
+ readonly bound: number;
55
+ }
50
56
  /**
51
- * The names a LimitError's `limit` holds, as Go's constants and Python's
52
- * `tinystore.limits` spell them, to map a limit without matching its text.
57
+ * The bounds one call meets, the same in every SDK and in Rust's
58
+ * `tinystore::limits`. A program cuts its batches to them before it calls,
59
+ * and tells which bound a LimitError met without reading its text:
53
60
  *
54
61
  * ```ts
55
- * if (err instanceof LimitError && err.limit === limits.decodedSamples) { … }
62
+ * for (let at = 0; at < courses.length; at += limits.setManyDocuments.bound) { … }
63
+ * if (err instanceof LimitError && err.limit === limits.requestBytes.name) { … }
56
64
  * ```
65
+ *
66
+ * A bound the store's options set, its memory (`store memory`) or its
67
+ * `maxSeries` (`series in a store`), is named the same way and is not here.
57
68
  */
58
69
  export declare const limits: Readonly<{
59
- readonly storeMemory: 'store memory';
60
- readonly storeMemoryNow: 'store memory, now';
61
- readonly matchedSeries: 'matched series';
62
- readonly decodedBlocks: 'decoded blocks';
63
- readonly fetchedBytes: 'fetched bytes';
64
- readonly decodedSamples: 'decoded samples';
65
- readonly outputSamples: 'output samples';
66
- readonly outputBuckets: 'output buckets';
67
- readonly recordBytes: "bytes of a record, a block's";
68
- readonly appendBytes: "bytes of records in one Append, a segment's; split it";
69
- readonly jobValueBytes: "bytes of a job's value";
70
- readonly stepBytes: "bytes of a step's answer";
71
- readonly objectBytes: "bytes of an object, the bucket's MaxSize";
72
- readonly rowBytes: "bytes of a call's rows";
70
+ /** A bucket's value, as it is stored. */
71
+ valueBytes: Limit;
72
+ /** A live setting's change, as JSON. */
73
+ settingBytes: Limit;
74
+ /** Every change a config keeps, together. */
75
+ configBytes: Limit;
76
+ /** The callers that wait for one lock or semaphore at once. */
77
+ lockWaiters: Limit;
78
+ /** The subscriptions to the store's channels at once. */
79
+ subscriptions: Limit;
80
+ /** A job's payload, its result or a step's answer, as JSON. */
81
+ jobBytes: Limit;
82
+ /** A run's progress, as JSON. */
83
+ progressBytes: Limit;
84
+ /** The values one call reads from a database: past them, read a page at a time. */
85
+ rowsBytes: Limit;
86
+ /** One event, its name, fields and text together. */
87
+ eventBytes: Limit;
88
+ /** The events of one append together. */
89
+ appendBytes: Limit;
90
+ /** The rows one `aggregate` answers. */
91
+ aggregateRows: Limit;
92
+ /** The different values one `top` or `distinct` holds, as JSON. */
93
+ countBytes: Limit;
94
+ /** The samples of one `ingest`. */
95
+ ingestSamples: Limit;
96
+ /** The bytes of one `ingest`'s samples, each with its labels. */
97
+ ingestBytes: Limit;
98
+ /** The samples of one exporter's text. */
99
+ textSamples: Limit;
100
+ /** One exporter's text, and the bytes of its samples. */
101
+ textBytes: Limit;
102
+ /** The series one query finds. */
103
+ querySeries: Limit;
104
+ /** What one query reads from the file. */
105
+ queryBytes: Limit;
106
+ /** The samples one query decodes. */
107
+ querySamples: Limit;
108
+ /** The samples or buckets one query answers. */
109
+ queryAnswer: Limit;
110
+ /** The documents of one `setMany`. */
111
+ setManyDocuments: Limit;
112
+ /** The documents of one `setMany` as JSON; one request body, `requestBytes`, bounds it first. */
113
+ setManyBytes: Limit;
114
+ /** One document as JSON, or a table's row as its index reads it. */
115
+ documentBytes: Limit;
116
+ /** The hits a search reaches, its offset and its limit together. */
117
+ searchHits: Limit;
118
+ /** A search's text, in bytes. */
119
+ searchText: Limit;
120
+ /** The conditions of one search's filter. */
121
+ filterConditions: Limit;
122
+ /** The values the lists of one search's conditions hold together. */
123
+ filterValues: Limit;
124
+ /** A text a filter keeps or asks for, in bytes. */
125
+ filterText: Limit;
126
+ /** A vector's dimensions. */
127
+ vectorDimensions: Limit;
128
+ /** One request, its message as the SDK sends it: a larger one fails before it is sent. */
129
+ requestBytes: Limit;
130
+ /** One answer, its message as the store sends it. */
131
+ answerBytes: Limit;
73
132
  }>;
74
133
  /** What the call needs is not there: a file to copy or rename. */
75
134
  export declare class NotFoundError extends TinystoreError {
package/dist/errors.js CHANGED
@@ -43,9 +43,10 @@ export class InvalidError extends TinystoreError {
43
43
  }
44
44
  }
45
45
  /**
46
- * A bound: memory, size or count. Later, or smaller, it may go through. A
47
- * limit the store names says which, what the call would have taken of it,
48
- * and the bound: `decoded samples`, 120000, 100000.
46
+ * A bound: memory, size or count. Later, or smaller, it may go through. The
47
+ * error names the bound, what the call would have taken of it, and the
48
+ * bound: `set_many documents`, 1001, 1000. `limits` holds the bounds a call
49
+ * meets by those names.
49
50
  */
50
51
  export class LimitError extends TinystoreError {
51
52
  limit;
@@ -58,29 +59,83 @@ export class LimitError extends TinystoreError {
58
59
  this.bound = typeof what?.bound === 'string' ? Number(what.bound) : undefined;
59
60
  }
60
61
  }
62
+ const limit = (name, bound) => Object.freeze({ name, bound });
61
63
  /**
62
- * The names a LimitError's `limit` holds, as Go's constants and Python's
63
- * `tinystore.limits` spell them, to map a limit without matching its text.
64
+ * The bounds one call meets, the same in every SDK and in Rust's
65
+ * `tinystore::limits`. A program cuts its batches to them before it calls,
66
+ * and tells which bound a LimitError met without reading its text:
64
67
  *
65
68
  * ```ts
66
- * if (err instanceof LimitError && err.limit === limits.decodedSamples) { … }
69
+ * for (let at = 0; at < courses.length; at += limits.setManyDocuments.bound) { … }
70
+ * if (err instanceof LimitError && err.limit === limits.requestBytes.name) { … }
67
71
  * ```
72
+ *
73
+ * A bound the store's options set, its memory (`store memory`) or its
74
+ * `maxSeries` (`series in a store`), is named the same way and is not here.
68
75
  */
69
76
  export const limits = Object.freeze({
70
- storeMemory: 'store memory',
71
- storeMemoryNow: 'store memory, now',
72
- matchedSeries: 'matched series',
73
- decodedBlocks: 'decoded blocks',
74
- fetchedBytes: 'fetched bytes',
75
- decodedSamples: 'decoded samples',
76
- outputSamples: 'output samples',
77
- outputBuckets: 'output buckets',
78
- recordBytes: "bytes of a record, a block's",
79
- appendBytes: "bytes of records in one Append, a segment's; split it",
80
- jobValueBytes: "bytes of a job's value",
81
- stepBytes: "bytes of a step's answer",
82
- objectBytes: "bytes of an object, the bucket's MaxSize",
83
- rowBytes: "bytes of a call's rows",
77
+ /** A bucket's value, as it is stored. */
78
+ valueBytes: limit('value bytes', 1 << 20),
79
+ /** A live setting's change, as JSON. */
80
+ settingBytes: limit('setting bytes', 16 << 10),
81
+ /** Every change a config keeps, together. */
82
+ configBytes: limit('config bytes', 256 << 10),
83
+ /** The callers that wait for one lock or semaphore at once. */
84
+ lockWaiters: limit('lock waiters', 10_000),
85
+ /** The subscriptions to the store's channels at once. */
86
+ subscriptions: limit('subscriptions', 10_000),
87
+ /** A job's payload, its result or a step's answer, as JSON. */
88
+ jobBytes: limit('job bytes', 1 << 20),
89
+ /** A run's progress, as JSON. */
90
+ progressBytes: limit('progress bytes', 4 << 10),
91
+ /** The values one call reads from a database: past them, read a page at a time. */
92
+ rowsBytes: limit("bytes of a call's rows", 64 << 20),
93
+ /** One event, its name, fields and text together. */
94
+ eventBytes: limit('event bytes', 256 << 10),
95
+ /** The events of one append together. */
96
+ appendBytes: limit('append bytes', 4 << 20),
97
+ /** The rows one `aggregate` answers. */
98
+ aggregateRows: limit('aggregate rows', 10_000),
99
+ /** The different values one `top` or `distinct` holds, as JSON. */
100
+ countBytes: limit('count bytes', 64 << 20),
101
+ /** The samples of one `ingest`. */
102
+ ingestSamples: limit('ingest samples', 10_000),
103
+ /** The bytes of one `ingest`'s samples, each with its labels. */
104
+ ingestBytes: limit('ingest bytes', 4 << 20),
105
+ /** The samples of one exporter's text. */
106
+ textSamples: limit('text samples', 100_000),
107
+ /** One exporter's text, and the bytes of its samples. */
108
+ textBytes: limit('text bytes', 32 << 20),
109
+ /** The series one query finds. */
110
+ querySeries: limit('series', 1000),
111
+ /** What one query reads from the file. */
112
+ queryBytes: limit('bytes read', 16 << 20),
113
+ /** The samples one query decodes. */
114
+ querySamples: limit('samples decoded', 1 << 20),
115
+ /** The samples or buckets one query answers. */
116
+ queryAnswer: limit('answer', 100_000),
117
+ /** The documents of one `setMany`. */
118
+ setManyDocuments: limit('set_many documents', 1000),
119
+ /** The documents of one `setMany` as JSON; one request body, `requestBytes`, bounds it first. */
120
+ setManyBytes: limit('set_many bytes', 16 << 20),
121
+ /** One document as JSON, or a table's row as its index reads it. */
122
+ documentBytes: limit('document bytes', 1 << 20),
123
+ /** The hits a search reaches, its offset and its limit together. */
124
+ searchHits: limit('search hits', 1000),
125
+ /** A search's text, in bytes. */
126
+ searchText: limit('search text', 1 << 10),
127
+ /** The conditions of one search's filter. */
128
+ filterConditions: limit('filter conditions', 8),
129
+ /** The values the lists of one search's conditions hold together. */
130
+ filterValues: limit('filter values', 100),
131
+ /** A text a filter keeps or asks for, in bytes. */
132
+ filterText: limit('filter text', 256),
133
+ /** A vector's dimensions. */
134
+ vectorDimensions: limit('vector dimensions', 4096),
135
+ /** One request, its message as the SDK sends it: a larger one fails before it is sent. */
136
+ requestBytes: limit('request bytes', 2 << 20),
137
+ /** One answer, its message as the store sends it. */
138
+ answerBytes: limit('answer bytes', 2 << 20),
84
139
  });
85
140
  /** What the call needs is not there: a file to copy or rename. */
86
141
  export class NotFoundError extends TinystoreError {
package/dist/index.d.ts CHANGED
@@ -18,7 +18,7 @@ export type { Once, OnceOptions } from './once.ts';
18
18
  export type { ColumnType, Query, RowPage, Table, TableOptions, UpsertOptions } from './query.ts';
19
19
  export type { Aggregate as EventsAggregate, AllEvents, AppendOptions, Counted, Damage, Event, EventLevel, Events, EventsOptions, Fields, Level, Levels, Lines, NewEvent, Page as EventsPage, PollBatch, Query as EventsQuery, Row as EventsRow, Stats, StoreLoggerOptions, StreamInfo, TailBatch, TailQuery, Top, } from './records.ts';
20
20
  export type { StandardSchemaV1 } from './schema.ts';
21
- export { type Found as SearchFound, type Hit as SearchHit, type IndexDocument, type IndexInfo, type IndexOptions, type IndexStatus, type Query as SearchQuery, SearchIndex, search, TableIndex, type TableIndexOptions, type Vector, type Where, type WhereValue, } from './search.ts';
21
+ export { type Found as SearchFound, type Hit as SearchHit, type IndexDocument, type IndexInfo, type IndexOptions, type IndexStatus, type KeyboardLayout, type Match as SearchMatch, type Query as SearchQuery, SearchIndex, search, TableIndex, type TableIndexOptions, type Vector, type Where, type WhereValue, } from './search.ts';
22
22
  export { type Columns, type Database, type DatabaseOptions, type Done, type Migrations, type Row, Sql, type SqlArg, type SqlTag, type SqlTx, type SqlValue, type Statement, sql, } from './sql.ts';
23
23
  export { type ConnectOptions, connect, type NodeOptions, type OpenOptions, open, type Status, Store, } from './store.ts';
24
24
  export type { Calendar, Duration, DurationText, Time } from './time.ts';
package/dist/kv.d.ts CHANGED
@@ -102,6 +102,21 @@ export declare class Bucket<T> {
102
102
  set(key: Key, value: T, options?: WriteOptions): Promise<void>;
103
103
  /** Writes the value only where no live key is, and says whether it did. */
104
104
  create(key: Key, value: T, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>;
105
+ /**
106
+ * Writes what `change` makes of the key's value without losing a write
107
+ * made meanwhile: it reads the key, calls `change` with its value, or
108
+ * undefined where it holds none, and writes what `change` returns at the
109
+ * version it read, or creates the key. When another write came first it
110
+ * reads again and calls `change` again, eight times at most, then throws
111
+ * ConflictError: `change` may run more than once, so it must do nothing
112
+ * else. A change that returns undefined, or the very value it was given,
113
+ * writes nothing. It returns the value written, or the one there when
114
+ * nothing was. A key that is there keeps its expiry, and one it creates
115
+ * takes the bucket's, as set and create do.
116
+ *
117
+ * await pinned.update(studentId, courses => [...(courses ?? []), 2518])
118
+ */
119
+ update(key: Key, change: (current: T | undefined) => T | undefined): Promise<T | undefined>;
105
120
  /** Puts the key in a bucket used as a set; false when it was there. */
106
121
  add(key: Key, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>;
107
122
  /**
package/dist/kv.js CHANGED
@@ -2,11 +2,13 @@
2
2
  // of one value type by key, keys in branches, expiry by the store's clock and
3
3
  // versions that never repeat, with counters beside them. A handle opens with
4
4
  // its first call on a connection.
5
- import { CorruptError, InvalidError } from './errors.js';
5
+ import { ConflictError, CorruptError, InvalidError } from './errors.js';
6
6
  import { checkName, handleOn, ownerText, viaLink, } from './handles.js';
7
7
  import { dateOf, ms, unixMs } from './time.js';
8
8
  import { textOf } from './wire/codec.js';
9
9
  import { KvBranch, KvBucketOpen, KvCall, KvCount, KvCountersOpen, KvEntry, KvFound, KvList, KvPage, KvResealed, KvWritten, methods, } from './wire/protocol.js';
10
+ /** The tries an update makes while other writes come first, as many as a config's change makes. */
11
+ const updateAttempts = 8;
10
12
  // a handle's parts, kept out of its public shape, for store.tx
11
13
  const parts = new WeakMap();
12
14
  export function partsOf(handle) {
@@ -69,6 +71,34 @@ export class Bucket {
69
71
  const raw = this.#values.encode(value);
70
72
  return this.#ask('kv.create', { key, value: raw, ...writeFields(options) }, 'write', written);
71
73
  }
74
+ /**
75
+ * Writes what `change` makes of the key's value without losing a write
76
+ * made meanwhile: it reads the key, calls `change` with its value, or
77
+ * undefined where it holds none, and writes what `change` returns at the
78
+ * version it read, or creates the key. When another write came first it
79
+ * reads again and calls `change` again, eight times at most, then throws
80
+ * ConflictError: `change` may run more than once, so it must do nothing
81
+ * else. A change that returns undefined, or the very value it was given,
82
+ * writes nothing. It returns the value written, or the one there when
83
+ * nothing was. A key that is there keeps its expiry, and one it creates
84
+ * takes the bucket's, as set and create do.
85
+ *
86
+ * await pinned.update(studentId, courses => [...(courses ?? []), 2518])
87
+ */
88
+ async update(key, change) {
89
+ for (let attempt = 0; attempt < updateAttempts; attempt++) {
90
+ const entry = await this.entry(key);
91
+ const next = change(entry?.value);
92
+ if (next === undefined || (entry !== undefined && next === entry.value)) {
93
+ return entry?.value;
94
+ }
95
+ if (await this.#written(key, next, entry?.version)) {
96
+ return next;
97
+ }
98
+ }
99
+ const shown = [this.#home?.describe, `kv bucket ${this.name}`, this.#shownKey(key)];
100
+ throw new ConflictError(`${shown.filter(part => part !== undefined).join(': ')}: other writes came first each time it was tried`);
101
+ }
72
102
  /** Puts the key in a bucket used as a set; false when it was there. */
73
103
  async add(key, options) {
74
104
  return this.#ask('kv.create', { key, ...writeFields(options) }, 'write', written);
@@ -135,6 +165,26 @@ export class Bucket {
135
165
  after = page.next;
136
166
  }
137
167
  }
168
+ // one try of an update: false when another write came first, at the key or creating it
169
+ async #written(key, next, version) {
170
+ try {
171
+ if (version === undefined) {
172
+ return await this.create(key, next);
173
+ }
174
+ await this.set(key, next, { ifVersion: version });
175
+ return true;
176
+ }
177
+ catch (err) {
178
+ if (err instanceof ConflictError) {
179
+ return false;
180
+ }
181
+ throw err;
182
+ }
183
+ }
184
+ // the key as the core's errors show it, after its branch's owners
185
+ #shownKey(key) {
186
+ return `key ${JSON.stringify([...this.#under, keyText(key)].join('/'))}`;
187
+ }
138
188
  // a call on one key: its fields written where they leave from, its answer read where it arrived
139
189
  #ask(method, fields, idempotence, read) {
140
190
  // the caller's own fields, made the call's: an object more a call is one too many
package/dist/logger.d.ts CHANGED
@@ -131,7 +131,12 @@ export declare class Logger {
131
131
  error(message: string, attrs?: Fields): void;
132
132
  /** An event of the stream: a record named for it, with no level and no body. */
133
133
  event(name: string, attrs?: Fields): void;
134
- /** The logger of the same stream, buffer and console, its context these fields besides its own. */
134
+ /**
135
+ * The logger of the same stream, buffer and console, its context these
136
+ * fields besides its own: a key it had already takes the new value where
137
+ * it stood, as an object spread does, where it prints, in what is kept
138
+ * and for a query's `where`.
139
+ */
135
140
  with(context: Fields): Logger;
136
141
  /** Hands what the buffer holds to the server now, as the timer does every second. */
137
142
  flush(): Promise<void>;
package/dist/logger.js CHANGED
@@ -303,12 +303,15 @@ export class Logger {
303
303
  }
304
304
  this.#emit({ event: name }, attrs);
305
305
  }
306
- /** The logger of the same stream, buffer and console, its context these fields besides its own. */
306
+ /**
307
+ * The logger of the same stream, buffer and console, its context these
308
+ * fields besides its own: a key it had already takes the new value where
309
+ * it stood, as an object spread does, where it prints, in what is kept
310
+ * and for a query's `where`.
311
+ */
307
312
  with(context) {
308
- return new Logger(this.#shared, [
309
- ...this.#context,
310
- ...encodeFields(context, this.#shared.redact, this.#shared.replace),
311
- ]);
313
+ const added = encodeFields(context, this.#shared.redact, this.#shared.replace);
314
+ return new Logger(this.#shared, onceEach(this.#context, added));
312
315
  }
313
316
  /** Hands what the buffer holds to the server now, as the timer does every second. */
314
317
  async flush() {
@@ -380,6 +383,27 @@ export class Logger {
380
383
  }
381
384
  }
382
385
  }
386
+ /**
387
+ * A context's key, JSON pairs with `added`'s after them, each key once: where
388
+ * it was first given, holding the value given last.
389
+ *
390
+ * ```text
391
+ * component=http user=7, then component=access → component=access user=7
392
+ * ```
393
+ */
394
+ function onceEach(context, added) {
395
+ const once = [...context];
396
+ for (let i = 0; i < added.length; i += 2) {
397
+ const at = once.findIndex((key, place) => place % 2 === 0 && key === added[i]);
398
+ if (at === -1) {
399
+ once.push(added[i], added[i + 1]);
400
+ }
401
+ else {
402
+ once[at + 1] = added[i + 1];
403
+ }
404
+ }
405
+ return once;
406
+ }
383
407
  /** Whether a logger prints a line of level: it has a console, and the level is the level printed or above. */
384
408
  function prints(shared, level) {
385
409
  return shared.print !== undefined && level >= (shared.printed ?? shared.kept);
package/dist/search.d.ts CHANGED
@@ -9,6 +9,12 @@ export interface IndexOptions {
9
9
  filters?: readonly string[] | undefined;
10
10
  /** a misspelt word read as the index's nearest; on unless false */
11
11
  typoTolerance?: boolean | undefined;
12
+ /**
13
+ * the keyboard layouts the index's readers type with, `['ru', 'en']`: a
14
+ * word that finds nothing as typed is read as the same keys type in the
15
+ * other layout, when it finds something there, and `corrected` says so
16
+ */
17
+ layouts?: readonly KeyboardLayout[] | undefined;
12
18
  /** a vector the program's model gives each document, and `recall` for searches from clusters */
13
19
  vectors?: {
14
20
  dimensions: number;
@@ -22,6 +28,8 @@ export interface IndexOptions {
22
28
  /** whether a change that needs every document read again waits for `store.reindex` */
23
29
  rebuild?: 'automatic' | 'manual' | undefined;
24
30
  }
31
+ /** A keyboard layout an index's readers type with: ЙЦУКЕН, or QWERTY. */
32
+ export type KeyboardLayout = 'ru' | 'en';
25
33
  /** A vector the program's own model gave, of the index's dimensions. */
26
34
  export type Vector = readonly number[] | Float32Array;
27
35
  /** A value a `where` matches: text, a number, a boolean, one of a list, a range, or `null` for none. */
@@ -54,15 +62,47 @@ export interface Query {
54
62
  vectorWeight?: number | undefined;
55
63
  rerank?: boolean | undefined;
56
64
  } | undefined;
65
+ /**
66
+ * the last word read as the start of a word too, as a search box types:
67
+ * `crypt` finds `cryptography` as well, at half its field's weight; a
68
+ * word a space follows is whole, and so is one of a single letter. With
69
+ * `'every'`, every word of two letters or more is read so, the first
70
+ * eight, as people shorten each word of a name: `лин алг` finds
71
+ * `Линейная алгебра`; a document that holds a word for each word of the
72
+ * text comes first, its score raised above the rest
73
+ */
74
+ prefix?: boolean | 'every' | undefined;
75
+ /**
76
+ * each hit says where the search's words matched it, in `matches`, as a
77
+ * search box shows them in bold: a word found as written, by its stem or
78
+ * once corrected whole, and a word a prefix began by the letters typed
79
+ */
80
+ matches?: boolean | undefined;
57
81
  /** 10 unless said; offset and limit together 1000 at most */
58
82
  limit?: number | undefined;
59
83
  offset?: number | undefined;
60
84
  }
85
+ /**
86
+ * Where a search's word matched a hit: `start` to `end` of a field's text in
87
+ * UTF-16 units, so that `text.slice(start, end)` is what matched.
88
+ */
89
+ export interface Match {
90
+ /** the field's path, or a table's column; `''` for a document that is its own text */
91
+ field: string;
92
+ /** the string's place in a field that holds a list */
93
+ item?: number;
94
+ start: number;
95
+ end: number;
96
+ /** the query's word, as its text wrote it */
97
+ word: string;
98
+ }
61
99
  /** A document a search found, and the score that ordered it among this search's hits. */
62
100
  export interface Hit<T> {
63
101
  id: string;
64
102
  value: T;
65
103
  score: number;
104
+ /** where the search's words matched it, when the search asked with `matches` */
105
+ matches?: Match[];
66
106
  }
67
107
  /** What a search found, the best first, and the text it read in fact when a word was misspelt. */
68
108
  export interface Found<T> {
@@ -102,6 +142,7 @@ export interface TableIndexOptions {
102
142
  /** the columns a search may keep its hits to; a boolean is the 1 or 0 SQLite keeps */
103
143
  filters?: readonly string[] | undefined;
104
144
  typoTolerance?: boolean | undefined;
145
+ layouts?: readonly KeyboardLayout[] | undefined;
105
146
  /** a column of blobs of little-endian floats, one a row or null, and `recall` for searches from clusters */
106
147
  vectors?: {
107
148
  column: string;
@@ -152,7 +193,12 @@ export declare class SearchIndex<T> extends Searchable<T> {
152
193
  set(id: Key, value: T, options?: {
153
194
  vector?: Vector | null | undefined;
154
195
  }): Promise<void>;
155
- /** Sets every document in one commit, all of them or none: 1,000 and 16 MiB at most. */
196
+ /**
197
+ * Sets every document in one commit, all of them or none: 1,000 at most,
198
+ * `limits.setManyDocuments`, and no more than one request body holds,
199
+ * 2 MiB, `limits.requestBytes`. Past either it fails with a LimitError
200
+ * that names the bound.
201
+ */
156
202
  setMany(documents: readonly IndexDocument<T>[]): Promise<void>;
157
203
  /** Deletes the document `id`; says whether there was one. */
158
204
  delete(id: Key): Promise<boolean>;
package/dist/search.js CHANGED
@@ -48,19 +48,27 @@ class Searchable {
48
48
  vector,
49
49
  vectorWeight: asked.hybrid?.vectorWeight,
50
50
  rerank: asked.hybrid?.rerank,
51
+ prefix: asked.prefix === true || undefined,
52
+ // none unless asked, so that a server before it reads the search
53
+ prefixEvery: asked.prefix === 'every' || undefined,
54
+ // JavaScript slices a string by its UTF-16 units
55
+ matches: asked.matches === true ? 'utf16' : undefined,
51
56
  where,
52
57
  offset: asked.offset,
53
58
  limit: asked.limit,
54
59
  });
55
60
  const found = SearchFound.decode(await this.call('search.search', body, 'read'));
56
61
  const columns = found.columns;
57
- const hits = (found.hits ?? []).map(hit => ({
58
- id: hit.id ?? '',
59
- value: (columns === undefined
62
+ const hits = (found.hits ?? []).map(hit => {
63
+ const value = (columns === undefined
60
64
  ? parseJson(hit.value ?? 'null')
61
- : rowsOf(columns, [(hit.row ?? [])])[0]),
62
- score: hit.score ?? 0,
63
- }));
65
+ : rowsOf(columns, [(hit.row ?? [])])[0]);
66
+ const read = { id: hit.id ?? '', value, score: hit.score ?? 0 };
67
+ if (hit.matches !== undefined) {
68
+ read.matches = hit.matches.map(matchOf);
69
+ }
70
+ return read;
71
+ });
64
72
  return found.corrected === undefined ? { hits } : { hits, corrected: found.corrected };
65
73
  }
66
74
  /** Where the index stands; a search never waits, and answers by the settings it serves. */
@@ -101,7 +109,12 @@ export class SearchIndex extends Searchable {
101
109
  const json = documentJson(this.name, value);
102
110
  await this.call('search.set', handle => SearchSet.encode({ handle, id: keyText(id), value: json, ...said }), 'write');
103
111
  }
104
- /** Sets every document in one commit, all of them or none: 1,000 and 16 MiB at most. */
112
+ /**
113
+ * Sets every document in one commit, all of them or none: 1,000 at most,
114
+ * `limits.setManyDocuments`, and no more than one request body holds,
115
+ * 2 MiB, `limits.requestBytes`. Past either it fails with a LimitError
116
+ * that names the bound.
117
+ */
105
118
  async setMany(documents) {
106
119
  const encoded = documents.map(document => ({
107
120
  id: keyText(document.id),
@@ -138,6 +151,7 @@ export function tableIndexOpen(name, options, database, reindex = false) {
138
151
  fields: fieldsOf(options.fields),
139
152
  filters: [...(options.filters ?? [])],
140
153
  typoTolerance: options.typoTolerance,
154
+ layouts: layoutsOf(options.layouts),
141
155
  dimensions: options.vectors?.dimensions,
142
156
  recall: options.vectors?.recall,
143
157
  vectorWeight: options.hybrid?.vectorWeight,
@@ -155,6 +169,10 @@ function fieldsOf(fields) {
155
169
  ? fields.map(path => ({ path, weight: 1 }))
156
170
  : Object.entries(fields ?? {}).map(([path, weight]) => ({ path, weight }));
157
171
  }
172
+ /** The layouts asked for; none left out, so that a server before them reads the open. */
173
+ function layoutsOf(layouts) {
174
+ return layouts?.length ? [...layouts] : undefined;
175
+ }
158
176
  /** The open of an index: its name, settings, and whether it reads the index again. */
159
177
  export function indexOpen(name, options = {}, reindex = false) {
160
178
  checkName(name, 'index');
@@ -163,6 +181,7 @@ export function indexOpen(name, options = {}, reindex = false) {
163
181
  fields: fieldsOf(options.fields),
164
182
  filters: [...(options.filters ?? [])],
165
183
  typoTolerance: options.typoTolerance,
184
+ layouts: layoutsOf(options.layouts),
166
185
  dimensions: options.vectors?.dimensions,
167
186
  recall: options.vectors?.recall,
168
187
  vectorWeight: options.hybrid?.vectorWeight,
@@ -203,6 +222,18 @@ function statusOf(status) {
203
222
  return { state: 'ready' };
204
223
  }
205
224
  }
225
+ function matchOf(found) {
226
+ const match = {
227
+ field: found.field ?? '',
228
+ start: found.start ?? 0,
229
+ end: found.end ?? 0,
230
+ word: found.word ?? '',
231
+ };
232
+ if (found.item !== undefined) {
233
+ match.item = found.item;
234
+ }
235
+ return match;
236
+ }
206
237
  function documentJson(name, value) {
207
238
  const json = JSON.stringify(value);
208
239
  if (json === undefined) {
package/dist/session.js CHANGED
@@ -5,11 +5,17 @@
5
5
  // socket, a Windows pipe, a child's stdio and TLS.
6
6
  import { createHmac, timingSafeEqual } from 'node:crypto';
7
7
  import { checkSignal, currentSignal, unlessCancelled } from './cancel.js';
8
- import { CancelledError, ClosedError, errorOf, LimitError, ProtocolError, UnavailableError, } from './errors.js';
8
+ import { CancelledError, ClosedError, errorOf, LimitError, limits, ProtocolError, UnavailableError, } from './errors.js';
9
9
  import { bodyLength, checkHeader, credit, Flag, frame, granted, headerSize, Kind, kindName, parseHeader, putHeader, } from './wire/frame.js';
10
10
  import { Reader, Writer } from './wire/msgpack.js';
11
- import { Failure, GoAway, Hello, Welcome } from './wire/protocol.js';
11
+ import { Failure, GoAway, Hello, methods, Welcome } from './wire/protocol.js';
12
12
  export const protocol = 1;
13
+ /** Each method's name by its number, as the schema spells it: `search.setMany`. */
14
+ const methodNames = new Map(Object.entries(methods).map(([name, number]) => [number, name]));
15
+ /** A method's name as the schema spells it, for an error the SDK says itself. */
16
+ function methodName(method) {
17
+ return methodNames.get(method) ?? `method ${method}`;
18
+ }
13
19
  /** What this client lets the server send on a stream before it grants more: a body at least. */
14
20
  export const downloadWindow = 2 << 20;
15
21
  /** The largest body a WELCOME may come in, before a body is agreed. */
@@ -260,7 +266,11 @@ export class Session {
260
266
  checkSignal(signal);
261
267
  const agreed = await unlessCancelled(this.welcomed, signal);
262
268
  if (body.length > agreed.maxBody) {
263
- throw new LimitError(`a request of ${body.length} bytes, past the ${agreed.maxBody} a body holds`);
269
+ throw new LimitError(`${methodName(method)}: a request of ${body.length} bytes, past the ${agreed.maxBody} a body holds`, {
270
+ limit: limits.requestBytes.name,
271
+ wanted: String(body.length),
272
+ bound: String(agreed.maxBody),
273
+ });
264
274
  }
265
275
  while (this.#streams.size >= agreed.inFlight && this.#usable() === undefined) {
266
276
  await this.#streamFreed(signal);