@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
@@ -0,0 +1,8 @@
1
+ import type { Ctx } from "./ctx.js";
2
+ import type { Infer, MessageDef, Shape } from "./schema.js";
3
+ /** Calls `endpoint` of `plugin` as the request's caller; a non-2xx answer throws an `RpcError` as `ctx.call`. */
4
+ export type Remote<I, O> = ((ctx: Ctx, input: I) => Promise<O>) & {
5
+ readonly plugin: string;
6
+ readonly endpoint: string;
7
+ };
8
+ export declare function remote<IS extends Shape, OS extends Shape>(plugin: string, endpoint: string, input: MessageDef<IS>, output: MessageDef<OS>): Remote<Infer<IS>, Infer<OS>>;
package/dist/remote.js ADDED
@@ -0,0 +1,19 @@
1
+ // A dependency's endpoint with its message types: what the clients `celobus plugin add` generates
2
+ // (`src/deps/<plugin>.ts`) export, `await catalog.getProduct(ctx, { id })`. The input is encoded and the answer
3
+ // decoded with the same codec as the plugin's own endpoints (bigint for int64, Date for timestamp, Decimal).
4
+ import { decodeMessage, encodeMessage } from "./codec.js";
5
+ import { internal } from "./errors.js";
6
+ export function remote(plugin, endpoint, input, output) {
7
+ const call = async (ctx, value) => {
8
+ const body = await ctx.call(plugin, endpoint, encodeMessage(input, value));
9
+ const errors = {};
10
+ const out = decodeMessage(output, body, "", errors);
11
+ const bad = Object.entries(errors);
12
+ if (bad.length > 0) {
13
+ const [path, why] = bad[0];
14
+ throw internal(`${plugin}.${endpoint} answered a body this plugin cannot read: ${path}: ${why}`);
15
+ }
16
+ return out;
17
+ };
18
+ return Object.assign(call, { plugin, endpoint });
19
+ }
@@ -0,0 +1,487 @@
1
+ import type { Decimal } from "./decimal.js";
2
+ /** The descriptor's scalar types. */
3
+ export type ScalarType = "string" | "bool" | "int32" | "int64" | "double" | "decimal" | "uuid" | "timestamp" | "date" | "bytes" | "json";
4
+ export type KeyType = "uuid" | "i64" | "string";
5
+ /**
6
+ * What a ref points at: an entity of this plugin (or a function returning it, for an entity declared later),
7
+ * the directory (`platform.user`, `platform.group` from `@celobus/sdk/platform`), or the canonical name of
8
+ * another plugin's entity (`'customers.customer'`) until dependencies have generated clients.
9
+ */
10
+ export type RefTarget = EntityDef<any> | (() => EntityDef<any>) | PlatformEntity | `${string}.${string}`;
11
+ /** @internal What a field holds. */
12
+ export interface FieldSpec {
13
+ kind: "scalar" | "message" | "enum" | "ref" | "array";
14
+ scalar?: ScalarType;
15
+ message?: MessageDef<Shape>;
16
+ enumDef?: EnumDef<string>;
17
+ ref?: RefTarget;
18
+ inner?: AnyField;
19
+ }
20
+ /** @internal The column modifiers of an entity's field. */
21
+ export interface ColumnSpec {
22
+ unique?: boolean;
23
+ index?: boolean;
24
+ encrypted?: boolean;
25
+ /** the text search language of a `searchable` column */
26
+ searchable?: string;
27
+ /** a ref's forward navigation name (default: the column's name without `_id`) */
28
+ nav?: string;
29
+ /** a ref's navigation on its target: the rows that point at a row of it */
30
+ inverse?: string;
31
+ /** what a ref does when its target is deleted for good */
32
+ onDelete?: OnDelete;
33
+ }
34
+ /**
35
+ * What a ref does when the row it names is deleted for good (`t.ref(target, { onDelete })`): within the plugin
36
+ * `restrict` (the default: the target is not deleted while rows refer to it), `cascade` (they are deleted with it),
37
+ * `setNull` (an optional ref is cleared), `noAction` (as `restrict`, checked at the end of the statement); to
38
+ * another plugin's entity or the directory `keep` (the default: the id stays) or, onto the directory, `setNull`.
39
+ * A soft delete of the target does nothing: the rows go (or are cleared) when it is removed for good.
40
+ */
41
+ export type OnDelete = "restrict" | "cascade" | "setNull" | "noAction" | "keep";
42
+ /** The options of a ref (`t.ref(target, { nav, inverse, onDelete })`). */
43
+ export interface RefOptions {
44
+ /** The forward navigation's name (`include('customer')`); by default the column's name without `Id`/`_id`. */
45
+ nav?: string;
46
+ /** A navigation on the target (an entity of this plugin): the rows of this entity that point at a row of it. */
47
+ inverse?: string;
48
+ /** What the ref does when its target is deleted for good ({@link OnDelete}). */
49
+ onDelete?: OnDelete;
50
+ }
51
+ /**
52
+ * What a ref field's target is at the type level when it is not an entity value (a thunk, another plugin's entity
53
+ * named by a string): a join along it is checked by the platform alone.
54
+ */
55
+ export declare const untypedRef: unique symbol;
56
+ export type UntypedRef = typeof untypedRef;
57
+ /** A field of a message or an entity: its type `T`, whether it may be absent (`O`), a ref's target (`R`). */
58
+ export declare class Field<T, O extends boolean = false, R = unknown> {
59
+ /** @internal */ readonly spec: FieldSpec;
60
+ /** @internal */ readonly isOptional: boolean;
61
+ /** @internal */ readonly description: string;
62
+ /** @internal */ readonly column: ColumnSpec;
63
+ readonly __type: T;
64
+ readonly __optional: O;
65
+ readonly __target: R;
66
+ constructor(
67
+ /** @internal */ spec: FieldSpec,
68
+ /** @internal */ isOptional?: boolean,
69
+ /** @internal */ description?: string,
70
+ /** @internal */ column?: ColumnSpec);
71
+ /** The field may be absent (`undefined` in TypeScript, omitted on the wire). Fields are required otherwise. */
72
+ optional(): Field<T, true, R>;
73
+ /** The field's description (descriptor, documentation, MCP). */
74
+ describe(text: string): Field<T, O, R>;
75
+ /** An entity column whose values are unique (among the rows that are not deleted, on a soft-delete entity). */
76
+ unique(): Field<T, O, R>;
77
+ /** An entity column with an index of its own (refs have one without it). */
78
+ index(): Field<T, O, R>;
79
+ /**
80
+ * A text column searched by full text (`note.f.title.search('words')`), in a PostgreSQL text search language
81
+ * (`simple` by default: no stemming).
82
+ */
83
+ searchable(language?: string): Field<T, O, R>;
84
+ /**
85
+ * An entity column the platform keeps encrypted at rest with the workspace's key (never unique, indexed, filtered,
86
+ * sorted, a ref, the id, the label or read by declared SQL).
87
+ */
88
+ encrypted(): Field<T, O>;
89
+ /** @internal A use of this field with its own identity (messages and entities copy their fields). */
90
+ use(): Field<T, O, R>;
91
+ }
92
+ export type AnyField = Field<any, boolean, any>;
93
+ export type Shape = {
94
+ [key: string]: AnyField;
95
+ };
96
+ /** The TypeScript type of a field's value. */
97
+ export type ValueOf<F> = F extends Field<infer T, any, any> ? T : never;
98
+ /** A ref field's target (`UntypedRef` for a thunk or a name; `unknown` for any other field). */
99
+ export type TargetOf<F> = F extends Field<any, any, infer R> ? R : unknown;
100
+ /** Whether a field may be absent. */
101
+ export type OptionalOf<F> = F extends Field<any, infer O, any> ? O : false;
102
+ type Simplify<T> = {
103
+ [K in keyof T]: T[K];
104
+ } & {};
105
+ type OptionalKeys<S> = {
106
+ [K in keyof S]: S[K] extends Field<any, true, any> ? K : never;
107
+ }[keyof S];
108
+ type RequiredKeys<S> = Exclude<keyof S, OptionalKeys<S>>;
109
+ /** The object type of a message with these fields: required fields present, optional ones may be absent. */
110
+ export type Infer<S extends Shape> = Simplify<{
111
+ [K in RequiredKeys<S>]: ValueOf<S[K]>;
112
+ } & {
113
+ [K in OptionalKeys<S>]?: ValueOf<S[K]> | undefined;
114
+ }>;
115
+ /**
116
+ * A typed handle of a message's field, for UI declarations: `order.f.status` is a `FieldRef<Order, OrderStatus>`
117
+ * (`M` is the message's value type, `T` the field's value type without `undefined`). A handle of another message
118
+ * does not fit where a field of `M` is expected, so a wrong field name or message is a type error.
119
+ */
120
+ export declare class FieldRef<M, T, R = unknown, O extends boolean = boolean> {
121
+ /** The descriptor's (snake_case) field name. */
122
+ readonly name: string;
123
+ /** @internal The field's declaration. */
124
+ readonly field: AnyField;
125
+ /** @internal The entity whose field this is (a query names its alias). */
126
+ readonly owner?: object | undefined;
127
+ readonly __message: (m: M) => M;
128
+ readonly __value: T;
129
+ /** a ref's target (`UntypedRef`: not known to the types) */
130
+ readonly __target: R;
131
+ /** whether the column may be null */
132
+ readonly __optional: O;
133
+ constructor(
134
+ /** The descriptor's (snake_case) field name. */
135
+ name: string,
136
+ /** @internal The field's declaration. */
137
+ field: AnyField,
138
+ /** @internal The entity whose field this is (a query names its alias). */
139
+ owner?: object | undefined);
140
+ private compare;
141
+ /** @internal A comparison with another column (`eqCol` and the others). */
142
+ private cmpCol;
143
+ /**
144
+ * In a query (`ctx.query(..)`): this column equals another of the same type (a key and a ref to its entity, two
145
+ * refs to one entity, two strings); also what `joinOn` joins on.
146
+ */
147
+ eqCol(other: ColumnOf<T, R>): ColCmp;
148
+ /** Not equal (a null is not equal to a value). */
149
+ neCol(other: ColumnOf<T, R>): ColCmp;
150
+ ltCol(other: ColumnOf<T, R>): ColCmp;
151
+ leCol(other: ColumnOf<T, R>): ColCmp;
152
+ gtCol(other: ColumnOf<T, R>): ColCmp;
153
+ geCol(other: ColumnOf<T, R>): ColCmp;
154
+ /** Rows whose field equals `v` (`ctx.db(order).find(order.f.status.eq('paid'))`). */
155
+ eq(v: T): Filter<M>;
156
+ /** Not equal (a null is not equal to a value). */
157
+ ne(v: T): Filter<M>;
158
+ lt(v: T): Filter<M>;
159
+ le(v: T): Filter<M>;
160
+ gt(v: T): Filter<M>;
161
+ ge(v: T): Filter<M>;
162
+ /** Any of the values. */
163
+ in(values: readonly T[]): Filter<M>;
164
+ isNull(): Filter<M>;
165
+ isNotNull(): Filter<M>;
166
+ /**
167
+ * Full-text search of a `searchable` column: the words as a web search reads them (`"a phrase"`, `or`, `-word`),
168
+ * in the column's language. The platform refuses it (400 `invalid`) on a column that is not searchable.
169
+ */
170
+ search(this: FieldRef<M, string, any, any>, words: string): Filter<M>;
171
+ /** A case-insensitive substring of a text column, taken literally (`%` and `_` are no wildcards). */
172
+ contains(this: FieldRef<M, string, any, any>, part: string): Filter<M>;
173
+ asc(): Order<M>;
174
+ desc(): Order<M>;
175
+ }
176
+ /** @internal A column of a query that is not a field handle: an alias's column (`query.ts`). */
177
+ export interface ColumnLike {
178
+ /** @internal */ readonly queryColumn: () => {
179
+ source: string;
180
+ field: string;
181
+ };
182
+ /** @internal */ readonly field: AnyField;
183
+ }
184
+ /** A column a column of type `T` (a ref to `R`) compares with: a field handle or an alias's column of that type. */
185
+ export type ColumnOf<T, R> = FieldRef<any, T, R extends UntypedRef ? any : R | UntypedRef, any> | (ColumnLike & {
186
+ readonly __value: T;
187
+ });
188
+ /** Two columns compared (`a.eqCol(b)`): a query's condition, and what `joinOn` joins on. */
189
+ export declare class ColCmp {
190
+ /** @internal */ readonly left: FieldRef<any, any, any, any> | ColumnLike;
191
+ /** @internal */ readonly op: string;
192
+ /** @internal */ readonly right: FieldRef<any, any, any, any> | ColumnLike;
193
+ constructor(
194
+ /** @internal */ left: FieldRef<any, any, any, any> | ColumnLike,
195
+ /** @internal */ op: string,
196
+ /** @internal */ right: FieldRef<any, any, any, any> | ColumnLike);
197
+ }
198
+ /** @internal A filter tree as the session carries it (`DbFilter`). */
199
+ export type WireFilter = {
200
+ and: {
201
+ items: WireFilter[];
202
+ };
203
+ } | {
204
+ or: {
205
+ items: WireFilter[];
206
+ };
207
+ } | {
208
+ not: WireFilter;
209
+ } | {
210
+ condition: {
211
+ field: string;
212
+ op: string;
213
+ values: Record<string, unknown>[];
214
+ };
215
+ };
216
+ /** A condition on the rows of `M`, from field handles; combined with `and`, `or`, `not`. */
217
+ export declare class Filter<M> {
218
+ /** @internal */ readonly node: WireFilter | undefined;
219
+ /** @internal The entity whose columns it tests (a query names its alias). */
220
+ readonly source?: object | undefined;
221
+ readonly __row: (m: M) => M;
222
+ constructor(
223
+ /** @internal */ node: WireFilter | undefined,
224
+ /** @internal The entity whose columns it tests (a query names its alias). */
225
+ source?: object | undefined);
226
+ /** Every row. */
227
+ static all<M>(): Filter<M>;
228
+ and(...others: Filter<M>[]): Filter<M>;
229
+ or(...others: Filter<M>[]): Filter<M>;
230
+ not(): Filter<M>;
231
+ }
232
+ /** All of the conditions. */
233
+ export declare function and<M>(...filters: Filter<M>[]): Filter<M>;
234
+ /** Any of the conditions. */
235
+ export declare function or<M>(...filters: Filter<M>[]): Filter<M>;
236
+ /** Not the condition. */
237
+ export declare function not<M>(filter: Filter<M>): Filter<M>;
238
+ /** A column the rows are ordered by. */
239
+ export declare class Order<M> {
240
+ readonly field: string;
241
+ readonly desc: boolean;
242
+ /** @internal The entity whose column it is (a query names its alias). */
243
+ readonly source?: object | undefined;
244
+ readonly __row: (m: M) => M;
245
+ constructor(field: string, desc: boolean,
246
+ /** @internal The entity whose column it is (a query names its alias). */
247
+ source?: object | undefined);
248
+ }
249
+ /** The field handles of a message with these fields. */
250
+ export type FieldRefs<M, S extends Shape> = {
251
+ readonly [K in keyof S & string]: FieldRef<M, ValueOf<S[K]>, TargetOf<S[K]>, OptionalOf<S[K]>>;
252
+ };
253
+ /** @internal The name each entity has in its plugin's descriptor, set when the plugin is described. */
254
+ export declare const entityNames: WeakMap<object, string>;
255
+ /** @internal A navigation of an entity: the target it brings (unknown for the directory or a named ref). */
256
+ export type NavInfo = {
257
+ kind: "forward";
258
+ target: EntityDef<any> | undefined;
259
+ } | {
260
+ kind: "inverse";
261
+ source: EntityDef<any>;
262
+ };
263
+ /** @internal Each entity's navigations by their (snake_case) names, set when the plugin is described. */
264
+ export declare const navigations: WeakMap<object, Map<string, NavInfo>>;
265
+ /** Maps fields to the descriptor path they were declared under, for `invalid(..).field(handle, ..)`. */
266
+ export declare const fieldKeys: WeakMap<AnyField, string>;
267
+ /** A named message (`t.message('HelloRequest', {...})`), usable as an endpoint's input or output or as a field. */
268
+ export declare class MessageDef<S extends Shape> extends Field<Infer<S>, false> {
269
+ readonly name: string;
270
+ /** the message's own description */
271
+ readonly messageDescription: string;
272
+ /**
273
+ * Fields at their protobuf default (`""`, `0`, `false`, an empty list, a message whose JSON is `{}`) are left out
274
+ * of its JSON; an enum and an optional field with a value are still written (`t.message(.., { omitDefaults: true })`).
275
+ */
276
+ readonly omitDefaults: boolean;
277
+ /** The fields as declared, each a handle for `invalid(..).field(message.fields.name, ..)`. */
278
+ readonly fields: S;
279
+ /** Typed field handles for UI declarations (`order.f.status`). */
280
+ readonly f: FieldRefs<Infer<S>, S>;
281
+ constructor(name: string, shape: S,
282
+ /** the message's own description */
283
+ messageDescription?: string,
284
+ /**
285
+ * Fields at their protobuf default (`""`, `0`, `false`, an empty list, a message whose JSON is `{}`) are left out
286
+ * of its JSON; an enum and an optional field with a value are still written (`t.message(.., { omitDefaults: true })`).
287
+ */
288
+ omitDefaults?: boolean);
289
+ }
290
+ /** A named enum (`t.enum('OrderStatus', ['placed', 'paid'])`); its values are strings on the wire and in code. */
291
+ export declare class EnumDef<V extends string> extends Field<V, false> {
292
+ readonly name: string;
293
+ readonly values: readonly V[];
294
+ constructor(name: string, values: readonly V[]);
295
+ }
296
+ /**
297
+ * An entity of the directory: `platform.user`, `platform.group` (refs name them), and for queries
298
+ * `platform.groupMember`, `platform.roleAssignment` (`@celobus/sdk/platform`). `f` are its columns' handles.
299
+ */
300
+ export declare class PlatformEntity<C extends Shape = Shape> {
301
+ readonly ref: "platform.user" | "platform.group" | "platform.group_member" | "platform.role_assignment";
302
+ /** Typed handles of the columns a query names (`platform.user.f.displayName`). */
303
+ readonly f: FieldRefs<PlatformRow<C>, C>;
304
+ /** @internal */ readonly columns: C;
305
+ constructor(ref: "platform.user" | "platform.group" | "platform.group_member" | "platform.role_assignment", columns?: C);
306
+ }
307
+ /** A row of a directory entity, as a query reads it. */
308
+ export type PlatformRow<C extends Shape> = Simplify<Infer<C>>;
309
+ export interface EntityOptions<C extends Shape> {
310
+ /**
311
+ * Another plugin's entity, which this plugin reads with `ctx.query(..)` (what `celobus plugin add` generates for a
312
+ * dependency's exported entity, with `name`); left out for an entity of this plugin.
313
+ */
314
+ plugin?: string;
315
+ /** The entity's name; by default its key in `plugin({ entities })`, in snake_case. */
316
+ name?: string;
317
+ description?: string;
318
+ /** Who makes the primary key `id`: `uuid` (default) or `i64` by the store, `string` by the author. */
319
+ key?: KeyType;
320
+ softDelete?: boolean;
321
+ version?: boolean;
322
+ appendOnly?: boolean;
323
+ /** The column that names a row; by default `name`, `title`, `number`, else `id`. */
324
+ label?: (keyof C & string) | "id";
325
+ /** The columns; `id` is implied by `key`. */
326
+ columns: C;
327
+ /**
328
+ * Indexes over several columns, each its columns in order (`'createdAt desc'` for a descending one; system columns
329
+ * may be named): `[['ownerId', 'createdAt desc']]`, or `{ columns: [...], unique: true }` for a unique one.
330
+ */
331
+ indexes?: readonly (readonly IndexColumn<C>[] | {
332
+ columns: readonly IndexColumn<C>[];
333
+ unique?: boolean;
334
+ })[];
335
+ /**
336
+ * Who reads, creates, changes and deletes the rows (`./access.ts`); without it no one but a system context does.
337
+ */
338
+ access?: (a: import("./access.js").AccessBuilder) => void;
339
+ }
340
+ type SystemColumn = "id" | "createdAt" | "updatedAt" | "deletedAt" | "version";
341
+ /** A column of an index: a column's key or a system column, optionally followed by ` desc` or ` asc`. */
342
+ export type IndexColumn<C> = (keyof C & string) | SystemColumn | `${(keyof C & string) | SystemColumn} ${"asc" | "desc"}`;
343
+ /**
344
+ * A dependency's entity this plugin reads (`ctx.query(customers.customer)`), as `celobus plugin add` generates it:
345
+ * the provider's plugin id, the entity's name there, its key and system columns, and the columns this plugin reads.
346
+ */
347
+ export interface ForeignEntityOptions<C extends Shape> {
348
+ /** The provider's plugin id. */
349
+ plugin: string;
350
+ /** The entity's name in the provider (snake_case). */
351
+ name: string;
352
+ description?: string;
353
+ key?: KeyType;
354
+ softDelete?: boolean;
355
+ version?: boolean;
356
+ columns: C;
357
+ }
358
+ /**
359
+ * An entity: one of the plugin's (`ctx.db(e)`), or a dependency's it reads (`ctx.query(e)`; `F` is `true`).
360
+ */
361
+ export declare class EntityDef<C extends Shape, F extends boolean = boolean> {
362
+ readonly options: EntityOptions<C>;
363
+ /** @internal `true`: another plugin's entity (`ctx.query`), never this plugin's (`ctx.db`). */
364
+ readonly __foreign: F;
365
+ readonly columns: C;
366
+ readonly key: KeyType;
367
+ /**
368
+ * Typed field handles of the entity's message for UI declarations and filters (`note.f.id`, `note.f.title`), and of
369
+ * its system columns (`note.f.createdAt`; `deletedAt` and `version` when it has them).
370
+ */
371
+ readonly f: FieldRefs<Row<EntityDef<C>>, C & {
372
+ id: Field<string, false, EntityDef<C, F>>;
373
+ } & SystemFields>;
374
+ constructor(options: EntityOptions<C>);
375
+ }
376
+ type SystemFields = {
377
+ createdAt: Field<Date, false>;
378
+ updatedAt: Field<Date, false>;
379
+ deletedAt: Field<Date, true>;
380
+ version: Field<bigint, false>;
381
+ };
382
+ /**
383
+ * Declares an entity: `entity({ key: 'i64', version: true, label: 'title', columns: { title: t.text() } })`; with
384
+ * `plugin` and `name`, a dependency's entity this plugin reads (generated by `celobus plugin add`).
385
+ */
386
+ export declare function entity<C extends Shape>(options: ForeignEntityOptions<C>): EntityDef<C, true>;
387
+ export declare function entity<C extends Shape>(options: EntityOptions<C> & {
388
+ plugin?: undefined;
389
+ }): EntityDef<C, false>;
390
+ /** @internal The provider of a dependency's entity; `undefined` for an entity of this plugin. */
391
+ export declare function foreignPlugin(e: EntityDef<any>): string | undefined;
392
+ /** A row of an entity, as endpoints answer it: `id` and the columns. */
393
+ export type Row<E> = E extends EntityDef<infer C> ? Simplify<{
394
+ id: string;
395
+ } & Infer<C>> : never;
396
+ /** A row as the repository returns it: the row and its system columns. */
397
+ export type Stored<E> = Simplify<Row<E> & {
398
+ createdAt: Date;
399
+ updatedAt: Date;
400
+ /** When a soft-delete entity's row was deleted (reads `withDeleted` see such rows). */
401
+ deletedAt?: Date;
402
+ /** On a versioned entity: what `expectVersion` checks. */
403
+ version?: bigint;
404
+ /** What `include(..)` brought, by the names it was given (absent when the read included nothing). */
405
+ included?: Included;
406
+ }>;
407
+ /** A row an `include` brought: the target's stored row (`id`, its columns, the system columns). */
408
+ export interface IncludedRow {
409
+ id: string;
410
+ createdAt: Date;
411
+ updatedAt: Date;
412
+ deletedAt?: Date;
413
+ version?: bigint;
414
+ [column: string]: unknown;
415
+ }
416
+ /**
417
+ * What an `include` brought, by the name it was given: a forward navigation's row (`undefined` when the ref is
418
+ * empty, or names a row the caller may not read) or an inverse navigation's rows (in id order).
419
+ */
420
+ export interface Included {
421
+ readonly [nav: string]: IncludedRow | IncludedRow[] | undefined;
422
+ }
423
+ /** What `create` takes: the columns, and `id` only for a `string` key (the store makes the others). */
424
+ export type Insert<E> = E extends EntityDef<infer C> ? Simplify<{
425
+ id?: string;
426
+ } & Infer<C>> : never;
427
+ /** What `update` takes: the columns it changes; `null` clears an optional one. */
428
+ export type Patch<E> = E extends EntityDef<infer C> ? {
429
+ [K in keyof Infer<C>]?: Infer<C>[K] | null;
430
+ } : never;
431
+ /** Field builders. Each maps to one descriptor type; the comment says the TypeScript and the wire type. */
432
+ export declare const t: {
433
+ /** string */
434
+ text: () => Field<string, false, unknown>;
435
+ /** string (the length is not checked) */
436
+ varchar: (_length?: number) => Field<string, false, unknown>;
437
+ /** boolean */
438
+ bool: () => Field<boolean, false, unknown>;
439
+ /** int32: a JS number, an integer */
440
+ int: () => Field<number, false, unknown>;
441
+ /** int64: a JS bigint; a string on the wire */
442
+ bigint: () => Field<bigint, false, unknown>;
443
+ /** double: a JS number */
444
+ double: () => Field<number, false, unknown>;
445
+ /** decimal: the SDK's `Decimal`; a string on the wire (precision and scale are not checked) */
446
+ decimal: (_precision?: number, _scale?: number) => Field<Decimal, false, unknown>;
447
+ /** uuid: a string in canonical form */
448
+ uuid: () => Field<string, false, unknown>;
449
+ /** timestamp: a JS `Date`; an RFC 3339 string on the wire */
450
+ timestamp: () => Field<Date, false, unknown>;
451
+ /** date: a `YYYY-MM-DD` string */
452
+ date: () => Field<string, false, unknown>;
453
+ /** bytes: a `Uint8Array`; base64 on the wire */
454
+ bytes: () => Field<Uint8Array<ArrayBufferLike>, false, unknown>;
455
+ /** json: any JSON value, typed as `T`; the value itself on the wire */
456
+ json: <T = unknown>() => Field<T, false, unknown>;
457
+ /** repeated: an array of the inner field's type (never absent: an empty array) */
458
+ array: <F extends AnyField>(inner: F) => Field<ValueOf<F>[], false>;
459
+ /**
460
+ * A reference to a row: its id as a string, whatever the target's key type (an `i64` key is its decimal
461
+ * string, as on the wire).
462
+ */
463
+ ref: typeof refBuilder;
464
+ /**
465
+ * A named message; also usable as a field (a nested message). `omitDefaults`: its fields at their protobuf default
466
+ * (`""`, `0`, `false`, an empty list, a message whose JSON is `{}`) are left out of the JSON it is written as (an
467
+ * enum, and an optional field that has a value, are still written), which trims the views a screen reads often.
468
+ */
469
+ message: <S extends Shape>(name: string, fields: S, options?: {
470
+ description?: string;
471
+ omitDefaults?: boolean;
472
+ }) => MessageDef<S>;
473
+ /** `t.enum('Name', [...values])` declares an enum; `t.enum(def)` is a field of it. */
474
+ enum: typeof enumBuilder;
475
+ };
476
+ /**
477
+ * A ref to an entity value (`t.ref(customer)`, `t.ref(platform.user)`) knows its target at the type level, so a query
478
+ * joins along it only to that entity; a ref by a thunk or a name does not.
479
+ */
480
+ declare function refBuilder<E extends EntityDef<any> | PlatformEntity<any>>(target: E, options?: RefOptions): Field<string, false, E>;
481
+ declare function refBuilder(target: RefTarget, options?: RefOptions): Field<string, false, UntypedRef>;
482
+ declare function enumBuilder<const V extends readonly string[]>(name: string, values: V): EnumDef<V[number]>;
483
+ declare function enumBuilder<V extends string>(def: EnumDef<V>): Field<V, false>;
484
+ /** The value type of an endpoint's input or output declaration. */
485
+ export type IoType = MessageDef<any> | EntityDef<any> | Shape;
486
+ export type IoValue<I> = I extends MessageDef<infer S> ? Infer<S> : I extends EntityDef<any> ? Row<I> : I extends Shape ? Infer<I> : never;
487
+ export {};