@celobus/sdk 0.0.0-stage → 0.1.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.
Files changed (48) hide show
  1. package/LICENSE +91 -0
  2. package/README.md +38 -2
  3. package/dist/access.d.ts +141 -0
  4. package/dist/access.js +232 -0
  5. package/dist/codec.d.ts +29 -0
  6. package/dist/codec.js +361 -0
  7. package/dist/cron.d.ts +2 -0
  8. package/dist/cron.js +113 -0
  9. package/dist/ctx.d.ts +644 -0
  10. package/dist/ctx.js +657 -0
  11. package/dist/db.d.ts +234 -0
  12. package/dist/db.js +495 -0
  13. package/dist/decimal.d.ts +39 -0
  14. package/dist/decimal.js +158 -0
  15. package/dist/declare.d.ts +311 -0
  16. package/dist/declare.js +78 -0
  17. package/dist/descriptor.d.ts +229 -0
  18. package/dist/descriptor.js +899 -0
  19. package/dist/errors.d.ts +65 -0
  20. package/dist/errors.js +114 -0
  21. package/dist/index.d.ts +17 -0
  22. package/dist/index.js +34 -0
  23. package/dist/log.d.ts +39 -0
  24. package/dist/log.js +101 -0
  25. package/dist/names.d.ts +12 -0
  26. package/dist/names.js +41 -0
  27. package/dist/notify.d.ts +185 -0
  28. package/dist/notify.js +234 -0
  29. package/dist/platform.d.ts +61 -0
  30. package/dist/platform.js +47 -0
  31. package/dist/plugin.d.ts +43 -0
  32. package/dist/plugin.js +117 -0
  33. package/dist/query.d.ts +326 -0
  34. package/dist/query.js +794 -0
  35. package/dist/remote.d.ts +8 -0
  36. package/dist/remote.js +19 -0
  37. package/dist/schema.d.ts +487 -0
  38. package/dist/schema.js +405 -0
  39. package/dist/serve.d.ts +63 -0
  40. package/dist/serve.js +411 -0
  41. package/dist/sql.d.ts +13 -0
  42. package/dist/sql.js +33 -0
  43. package/dist/ui.d.ts +1867 -0
  44. package/dist/ui.js +3964 -0
  45. package/dist/viz-kinds.d.ts +12 -0
  46. package/dist/viz-kinds.js +14 -0
  47. package/package.json +33 -4
  48. package/proto/plugin.proto +994 -0
package/dist/db.d.ts ADDED
@@ -0,0 +1,234 @@
1
+ import { Decimal } from "./decimal.js";
2
+ import type { EntityDef, Filter, Insert, Order, Patch, Row, Stored } from "./schema.js";
3
+ /** @internal What the repository needs of its context: a syscall, the request it is part of, its transaction. */
4
+ export interface DbLink {
5
+ syscall(call: Record<string, unknown>): Promise<DbResult>;
6
+ requestId: string;
7
+ tx: string;
8
+ /** the reason of a system context (`ctx.asSystem`); "" for the caller's */
9
+ asSystem: string;
10
+ }
11
+ /** @internal The members of `SyscallResult` the repository reads. */
12
+ export interface DbResult {
13
+ dbRows?: {
14
+ rows?: Buffer[];
15
+ nextPageToken?: string;
16
+ included?: Buffer[];
17
+ } | null;
18
+ dbCount?: {
19
+ count: string | number;
20
+ } | null;
21
+ dbGroups?: {
22
+ groups?: {
23
+ key: Buffer;
24
+ value: Buffer;
25
+ }[];
26
+ } | null;
27
+ txBegun?: {
28
+ tx: string;
29
+ } | null;
30
+ }
31
+ /** How a lock read waits for a row another transaction holds. */
32
+ export type LockWait = "wait" | "nowait" | "skipLocked";
33
+ /** A row lock of a read in a transaction: `update` (`FOR UPDATE`) or `share` (`FOR SHARE`). */
34
+ export type LockStrength = "update" | "share";
35
+ /** A page of rows and the token of the next one (`undefined`: the last page). */
36
+ export interface Page<R> {
37
+ rows: R[];
38
+ next?: string;
39
+ }
40
+ /** A call that goes when it is awaited, after options such as `expectVersion`. */
41
+ export declare class Pending<T> implements PromiseLike<T> {
42
+ private readonly run;
43
+ constructor(run: () => Promise<T>);
44
+ then<A = T, B = never>(onOk?: ((v: T) => A | PromiseLike<A>) | null, onErr?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
45
+ }
46
+ /** An update: `await db.update(id, patch).expectVersion(v)`. */
47
+ export declare class Update<E extends EntityDef<any>> extends Pending<Stored<E>> {
48
+ private expected?;
49
+ constructor(send: (expected?: bigint) => Promise<Stored<E>>);
50
+ /** Refuses the update (409 `version_conflict`) unless the row is at this version. */
51
+ expectVersion(v: bigint | number | undefined): this;
52
+ }
53
+ /** A delete: `await db.delete(id).expectVersion(v)`. */
54
+ export declare class Delete extends Pending<void> {
55
+ private expected?;
56
+ constructor(send: (expected?: bigint) => Promise<void>);
57
+ expectVersion(v: bigint | number | undefined): this;
58
+ }
59
+ /** A query being built: `db.find(filter).orderBy(..).limit(..)`, read with `all()`, `first()` or `page()`. */
60
+ export declare class Find<E extends EntityDef<any>> {
61
+ private readonly repo;
62
+ private readonly filter;
63
+ private readonly order;
64
+ private size;
65
+ private token;
66
+ private deleted;
67
+ private readonly navs;
68
+ /** @internal set by the lock methods of `TxFind` */
69
+ protected lockStrength?: LockStrength;
70
+ /** @internal */
71
+ protected lockWait?: LockWait;
72
+ constructor(repo: ReadRepository<E>, filter: Filter<Row<E>>);
73
+ /**
74
+ * Brings each row's navigations with it, read under their targets' own rules: a forward one (a ref's `nav`, by
75
+ * default the column's name without `Id`, or the ref column itself) brings the row it names, an inverse one the
76
+ * rows that point at this one. They come back in `row.included`, under the names given here; the rows they bring
77
+ * count toward the 1,000 of a read (422 `query_rows_limit`).
78
+ */
79
+ include(...navs: string[]): this;
80
+ /** Orders by a column; called again, by the next one (ties end by id). */
81
+ orderBy(o: Order<Row<E>>): this;
82
+ /** Rows per page (100 at most; 100 by default). */
83
+ limit(n: number): this;
84
+ /** The page after the one whose `next` this is. */
85
+ pageToken(token: string): this;
86
+ /** Soft-deleted rows too. */
87
+ withDeleted(): this;
88
+ private send;
89
+ /** Every matching row: more than 1,000 is 422 `query_rows_limit` (page through them instead). */
90
+ all(): Promise<Stored<E>[]>;
91
+ first(): Promise<Stored<E> | undefined>;
92
+ page(): Promise<Page<Stored<E>>>;
93
+ }
94
+ /**
95
+ * A query in a transaction (`tx.db(e).find(f)`), which may lock the rows it reads until the transaction ends:
96
+ * `forUpdate()` or `forShare()`, then `nowait()` (409 `row_locked` at once instead of waiting) or `skipLocked()`
97
+ * (leaves out the rows another transaction holds: a work queue). Waiting counts against the transaction's 5 s.
98
+ */
99
+ export declare class TxFind<E extends EntityDef<any>> extends Find<E> {
100
+ /** Locks the rows read against changes (`FOR UPDATE`). */
101
+ forUpdate(): this;
102
+ /** Locks the rows read against changes by others, letting them lock for share too (`FOR SHARE`). */
103
+ forShare(): this;
104
+ /** Fails at once with 409 `row_locked` when a row is held by another transaction. */
105
+ nowait(): this;
106
+ /** Leaves out the rows another transaction holds. */
107
+ skipLocked(): this;
108
+ }
109
+ /**
110
+ * The reads of an entity: of a dependency's (`ctx.query(customer)`, which has no writes), and of the plugin's own
111
+ * (`Repository`, which adds them).
112
+ */
113
+ export declare class ReadRepository<E extends EntityDef<any>> {
114
+ /** @internal */ readonly link: DbLink;
115
+ /** @internal */ readonly entity: E;
116
+ /** @internal */ readonly name: string;
117
+ /** @internal the provider whose entity this reads; "" for the plugin's own */
118
+ readonly dependency: string;
119
+ constructor(
120
+ /** @internal */ link: DbLink,
121
+ /** @internal */ entity: E,
122
+ /** @internal */ name: string,
123
+ /** @internal the provider whose entity this reads; "" for the plugin's own */
124
+ dependency?: string);
125
+ /** @internal */
126
+ head(): {
127
+ requestId: string;
128
+ tx: string;
129
+ entity: string;
130
+ asSystem: string;
131
+ dependency?: string;
132
+ };
133
+ /** @internal */
134
+ send(call: Record<string, unknown>): Promise<DbResult>;
135
+ /**
136
+ * A row by id; 404 `not_found` when there is none, or it is soft-deleted (`withDeleted` reads those too).
137
+ * `include` brings its navigations (`Find.include`).
138
+ */
139
+ get(id: string, options?: GetOptions): Promise<Stored<E>>;
140
+ /** @internal */
141
+ protected getting(id: string, options: GetOptions, strength: LockStrength | undefined, wait: LockWait | undefined): Promise<Stored<E>>;
142
+ /**
143
+ * Groups of the rows `where` matches (every row without it; soft-deleted ones only `withDeleted`), read under the
144
+ * entity's rules as any read: by the values of `groupBy` (none: one group of every row), each with its `count` of
145
+ * rows or the `sum` of a number column (int32 and int64 sum to a bigint, a decimal to a `Decimal`, a double to a
146
+ * number; a group of none sums to 0). In the order of the keys (nulls, `undefined` here, last); more than 1,000
147
+ * groups is 422 `query_rows_limit`.
148
+ */
149
+ aggregate<K extends ColumnKey<E> | undefined = undefined>(query: AggregateQuery<E, K> & {
150
+ count: true;
151
+ }): Promise<(GroupKey<E, K> & {
152
+ count: number;
153
+ })[]>;
154
+ aggregate<K extends ColumnKey<E> | undefined = undefined, S extends ColumnKey<E> = ColumnKey<E>>(query: AggregateQuery<E, K> & {
155
+ sum: S;
156
+ }): Promise<(GroupKey<E, K> & {
157
+ sum: SumOf<StoredValue<E, S>>;
158
+ })[]>;
159
+ /** The rows matching `filter` (every row without one). */
160
+ find(filter?: Filter<Row<E>>): Find<E>;
161
+ count(filter?: Filter<Row<E>>): Promise<number>;
162
+ exists(filter: Filter<Row<E>>): Promise<boolean>;
163
+ /** Every row: more than 1,000 is 422 `query_rows_limit` (page through them with `find().page()` instead). */
164
+ all(): Promise<Stored<E>[]>;
165
+ }
166
+ /** The options of `get`. */
167
+ export interface GetOptions {
168
+ /** A soft-deleted row too. */
169
+ withDeleted?: boolean;
170
+ /** Navigations to bring with the row (`Find.include`). */
171
+ include?: readonly string[];
172
+ }
173
+ /** The options of `get` in a transaction: a row lock besides. */
174
+ export interface TxGetOptions extends GetOptions {
175
+ /** Locks the row until the transaction ends. */
176
+ lock?: LockStrength;
177
+ /** How the lock waits (`wait` by default; `nowait`: 409 `row_locked` at once). */
178
+ wait?: LockWait;
179
+ }
180
+ /** A column of the entity's row (a TypeScript key), a system column included. */
181
+ export type ColumnKey<E> = keyof Stored<E> & string;
182
+ type StoredValue<E, K> = K extends keyof Stored<E> ? Exclude<Stored<E>[K], undefined> : never;
183
+ /** What an aggregate reads: which rows (`where`, `withDeleted`) and the column it groups by. */
184
+ export interface AggregateQuery<E extends EntityDef<any>, K> {
185
+ where?: Filter<Row<E>>;
186
+ withDeleted?: boolean;
187
+ groupBy?: K;
188
+ }
189
+ /** A group's key: the `groupBy` column's value (`undefined` for the rows without one). */
190
+ export type GroupKey<E, K> = K extends string ? {
191
+ [P in K]: StoredValue<E, P> | undefined;
192
+ } : {};
193
+ /** The sum of a column of this type. */
194
+ export type SumOf<V> = V extends Decimal ? Decimal : V extends bigint ? bigint : V extends number ? number | bigint : never;
195
+ /** The repository of an entity of the plugin: `ctx.db(order)` (in a transaction, `tx.db(order)`). */
196
+ export declare class Repository<E extends EntityDef<any>> extends ReadRepository<E> {
197
+ constructor(link: DbLink, entity: E, name: string);
198
+ /** A new row: the store makes a `uuid` or `i64` key; a `string` key is the row's `id`. */
199
+ create(row: Insert<E>): Promise<Stored<E>>;
200
+ /** New rows, in one statement (at most 1,000). */
201
+ createMany(rows: Insert<E>[]): Promise<Stored<E>[]>;
202
+ /** Changes the fields `patch` names (`null` clears an optional one); `.expectVersion(v)` checks the row's version. */
203
+ update(id: string, patch: Patch<E>): Update<E>;
204
+ /** Deletes a row (marks it, on a soft-delete entity); `.expectVersion(v)` checks its version. */
205
+ delete(id: string): Delete;
206
+ /** Removes a row of a soft-delete entity for good. */
207
+ deleteForce(id: string): Delete;
208
+ /**
209
+ * Changes the fields `patch` names on every row `where` matches that the caller may read (`Filter.all()` for
210
+ * every row), in one statement: each row passes the `update` rule and the guards as `update` does (one that does
211
+ * not refuses them all: 403); `version` and `updatedAt` move on each. More than 1,000 rows is 422 `bulk_limit`,
212
+ * and nothing is written. Answers how many rows changed.
213
+ */
214
+ updateWhere(where: Filter<Row<E>>, patch: Patch<E>): Promise<number>;
215
+ /**
216
+ * Creates `row`, or changes the row with the same value of the unique column `on` to it (`id` only for a
217
+ * `string` key): the new row passes the `create` rule, the changed one the `update` rule and the guards.
218
+ */
219
+ upsert(on: (keyof Row<E> & string), row: Insert<E>): Promise<Stored<E>>;
220
+ /** @internal A patch as the row's JSON writes it. */
221
+ protected patchJson(patch: Patch<E>, what: string): Record<string, unknown>;
222
+ /** Brings a soft-deleted row back. */
223
+ restore(id: string): Promise<Stored<E>>;
224
+ private deleting;
225
+ }
226
+ /**
227
+ * The repository of an entity in a transaction (`tx.db(order)`): reads may lock their rows until it ends, with
228
+ * `get(id, { lock: 'update' })` and `find(f).forUpdate()`; outside a transaction they are refused (400 `invalid`).
229
+ */
230
+ export declare class TxRepository<E extends EntityDef<any>> extends Repository<E> {
231
+ get(id: string, options?: TxGetOptions): Promise<Stored<E>>;
232
+ find(filter?: Filter<Row<E>>): TxFind<E>;
233
+ }
234
+ export {};