@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,326 @@
1
+ import { Decimal } from "./decimal.js";
2
+ import type { DbLink, DbResult, Find, GetOptions } from "./db.js";
3
+ import { ReadRepository } from "./db.js";
4
+ import { ColCmp, EntityDef, FieldRef, Filter, Order, PlatformEntity, type AnyField, type ColumnLike, type PlatformRow, type Row, type Stored, type UntypedRef } from "./schema.js";
5
+ import type { SumOf } from "./db.js";
6
+ /** An entity a query names: one of the plugin's, a dependency's exported one, the directory's. */
7
+ export type Queryable = EntityDef<any> | PlatformEntity<any>;
8
+ /** The row type of an entity, as its field handles name it. */
9
+ export type RowOf<E> = E extends EntityDef<any> ? Row<E> : E extends PlatformEntity<infer C> ? PlatformRow<C> : never;
10
+ /** A ref a join follows between `T` and an entity of the query: a field of `T` (`orderLine.f.orderId` joins
11
+ * `orderLine` to a query that has `order`), or a ref to `T` (`orderLine.f.orderId` joins `order`). */
12
+ export type JoinRefOf<T> = FieldRef<RowOf<T>, any, any, any> | FieldRef<any, any, T | UntypedRef, any>;
13
+ /** @internal */ export type WColumn = {
14
+ source: string;
15
+ field: string;
16
+ };
17
+ /** @internal */ export type WAgg = {
18
+ fn: string;
19
+ column?: WColumn;
20
+ };
21
+ /** @internal */ export type WTerm = {
22
+ column?: WColumn;
23
+ aggregate?: WAgg;
24
+ };
25
+ /** @internal */ export type WExpr = {
26
+ and: {
27
+ items: WExpr[];
28
+ };
29
+ } | {
30
+ or: {
31
+ items: WExpr[];
32
+ };
33
+ } | {
34
+ not: WExpr;
35
+ } | {
36
+ compare: {
37
+ left: WTerm;
38
+ op: string;
39
+ values?: Record<string, unknown>[];
40
+ right?: WTerm;
41
+ };
42
+ } | {
43
+ exists: {
44
+ source: {
45
+ entity: string;
46
+ alias: string;
47
+ };
48
+ filter?: WExpr;
49
+ };
50
+ };
51
+ /** The name of an entity in a query: `order`, `crm.customer`, `platform.user`. */
52
+ export declare function canonicalOf(e: object): string;
53
+ /** The alias of an entity unless it is given one: its name with `_` for `.` (`crm_customer`). */
54
+ export declare function defaultAlias(e: object): string;
55
+ /** A condition of a query beyond one entity's filter: `exists`, a column against a column, an aggregate's comparison,
56
+ * and the `and`, `or`, `not` of conditions of any entities. */
57
+ export declare class QCond {
58
+ readonly expr: WExpr | undefined;
59
+ constructor(/** @internal */ expr: WExpr | undefined);
60
+ }
61
+ /** What a query's `where` and `having` take: a field handle's filter (`order.f.status.eq('paid')`) of an entity of the
62
+ * query, a comparison of two columns, a `QCond`. */
63
+ export type CondLike = Filter<any> | ColCmp | QCond;
64
+ /** @internal */
65
+ export declare function exprOf(c: CondLike): WExpr | undefined;
66
+ /** All of the conditions (of any entities). */
67
+ export declare function and(...conds: CondLike[]): QCond;
68
+ /** Any of the conditions. */
69
+ export declare function or(...conds: CondLike[]): QCond;
70
+ /** Not the condition. */
71
+ export declare function not(cond: CondLike): QCond;
72
+ /** A row of `entity` (or of an alias) for which the conditions hold exists; they may name the query's entities. */
73
+ export declare function exists(entity: Queryable | Alias<any, boolean>, ...conds: CondLike[]): QCond;
74
+ /** No row of `entity` for which the conditions hold exists. */
75
+ export declare function notExists(entity: Queryable | Alias<any, boolean>, ...conds: CondLike[]): QCond;
76
+ /** A column of an aliased entity (`manager.f.displayName`): `T` its value, `O` whether it may be null. */
77
+ export declare class AliasCol<T, O extends boolean, R = unknown> implements ColumnLike {
78
+ /** @internal */ readonly alias: string;
79
+ /** @internal */ readonly name: string;
80
+ /** @internal */ readonly field: AnyField;
81
+ readonly __value: T;
82
+ readonly __optional: O;
83
+ readonly __target: R;
84
+ constructor(
85
+ /** @internal */ alias: string,
86
+ /** @internal */ name: string,
87
+ /** @internal */ field: AnyField);
88
+ /** @internal */
89
+ readonly queryColumn: () => WColumn;
90
+ private compare;
91
+ eq(v: T): QCond;
92
+ ne(v: T): QCond;
93
+ lt(v: T): QCond;
94
+ le(v: T): QCond;
95
+ gt(v: T): QCond;
96
+ ge(v: T): QCond;
97
+ in(values: readonly T[]): QCond;
98
+ isNull(): QCond;
99
+ isNotNull(): QCond;
100
+ eqCol(other: FieldRef<any, T, any, any> | AliasCol<T, any, any>): ColCmp;
101
+ asc(): QOrder;
102
+ desc(): QOrder;
103
+ }
104
+ type AliasCols<T, Left extends boolean> = {
105
+ readonly [K in keyof FieldsOf<T>]: FieldsOf<T>[K] extends FieldRef<any, infer V, infer R, infer O> ? AliasCol<V, Left extends true ? true : O, R> : never;
106
+ };
107
+ type FieldsOf<T> = T extends {
108
+ f: infer F;
109
+ } ? F : never;
110
+ /** An entity under a name of its own, for an entity joined twice: `alias(platform.user, 'manager')` (inner) or
111
+ * `.left()`; join it with `joinAs`, name its columns with `f`. */
112
+ export declare class Alias<T extends Queryable, Left extends boolean = false> {
113
+ /** @internal */ readonly entity: T;
114
+ readonly name: string;
115
+ /** @internal */ readonly isLeft: Left;
116
+ /** The alias's columns (`manager.f.displayName`). */
117
+ readonly f: AliasCols<T, Left>;
118
+ constructor(
119
+ /** @internal */ entity: T, name: string,
120
+ /** @internal */ isLeft: Left);
121
+ /** The alias joined left: its columns may be null. */
122
+ left(): Alias<T, true>;
123
+ }
124
+ /** An alias of an entity (`[a-z][a-z0-9_]*`). */
125
+ export declare function alias<T extends Queryable>(entity: T, name: string): Alias<T, false>;
126
+ /** An order of a query: a field handle's (`order.f.total.desc()`), an alias column's, an aggregate's. */
127
+ export declare class QOrder {
128
+ readonly wire: {
129
+ term: WTerm;
130
+ desc: boolean;
131
+ };
132
+ constructor(/** @internal */ wire: {
133
+ term: WTerm;
134
+ desc: boolean;
135
+ });
136
+ }
137
+ /** An aggregate whose value is an `O`: selected, ordered by, or compared in `having`. */
138
+ export declare class Agg<O> {
139
+ /** @internal */ readonly wire: WAgg;
140
+ /** @internal */ readonly read: (v: unknown) => O;
141
+ readonly __out: O;
142
+ constructor(
143
+ /** @internal */ wire: WAgg,
144
+ /** @internal */ read: (v: unknown) => O);
145
+ private compare;
146
+ eq(v: NonNullable<O>): QCond;
147
+ ne(v: NonNullable<O>): QCond;
148
+ lt(v: NonNullable<O>): QCond;
149
+ le(v: NonNullable<O>): QCond;
150
+ gt(v: NonNullable<O>): QCond;
151
+ ge(v: NonNullable<O>): QCond;
152
+ asc(): QOrder;
153
+ desc(): QOrder;
154
+ }
155
+ type AnyColumn = FieldRef<any, any, any, any> | AliasCol<any, any, any>;
156
+ type ValueOfColumn<C> = C extends FieldRef<any, infer T, any, any> ? T : C extends AliasCol<infer T, any, any> ? T : never;
157
+ /** The rows (of a group). */
158
+ export declare function count(): Agg<number>;
159
+ /** The distinct values of a column (nulls not counted). */
160
+ export declare function countDistinct(c: AnyColumn): Agg<number>;
161
+ /** The sum of a number column: int32 and int64 sum to a bigint, a decimal to a `Decimal`, a double to a number (0
162
+ * when there is none). */
163
+ export declare function sum<C extends AnyColumn>(c: C): Agg<SumOf<ValueOfColumn<C>>>;
164
+ /** The average of a number column: a `Decimal` of integers and decimals, a number of doubles (`undefined` when every
165
+ * value is null). */
166
+ export declare function avg<C extends AnyColumn>(c: C): Agg<AvgOf<ValueOfColumn<C>> | undefined>;
167
+ /** The average of a column of this type. */
168
+ export type AvgOf<V> = V extends Decimal ? Decimal : V extends bigint ? Decimal : V extends number ? Decimal | number : never;
169
+ /** The smallest value of a column (`undefined` when there is none). */
170
+ export declare function min<C extends AnyColumn>(c: C): Agg<ValueOfColumn<C> | undefined>;
171
+ /** The largest value of a column (`undefined` when there is none). */
172
+ export declare function max<C extends AnyColumn>(c: C): Agg<ValueOfColumn<C> | undefined>;
173
+ /** A row's label as `label(ref)` selects it: a person's (or a group's) name and avatar, another row's label column. */
174
+ export interface Label {
175
+ id: string;
176
+ text: string;
177
+ avatarUrl?: string;
178
+ }
179
+ /** A `label(..)` select item. */
180
+ export declare class LabelItem {
181
+ readonly column: WColumn;
182
+ constructor(/** @internal */ column: WColumn);
183
+ }
184
+ /** The label of the row a ref names (or of the row of an `id`): for every reader of that row, a guest included;
185
+ * `undefined` when the ref is empty or names a row the caller may not read. */
186
+ export declare function label(ref: FieldRef<any, string, any, any> | AliasCol<string, any, any>): LabelItem;
187
+ type ColumnIn<X> = X extends any ? FieldRef<X, any, any, any> : never;
188
+ /** An item `select` takes over the entities `X` of the query. */
189
+ export type SelectItem<X> = ColumnIn<X> | AliasCol<any, any, any> | Agg<any> | LabelItem;
190
+ /** The value of a select item: a left-joined entity's column (and an optional one) may be `undefined`. */
191
+ export type ItemValue<I, L> = I extends FieldRef<infer M, infer T, any, infer O> ? [M] extends [L] ? T | undefined : O extends true ? T | undefined : T : I extends AliasCol<infer T, infer O, any> ? O extends true ? T | undefined : T : I extends Agg<infer V> ? V : I extends LabelItem ? Label | undefined : never;
192
+ type CondIn<X> = (X extends any ? Filter<X> : never) | ColCmp | QCond;
193
+ type OrderIn<X> = (X extends any ? Order<X> : never) | QOrder;
194
+ type Reader = (row: unknown[]) => Record<string, unknown>;
195
+ /** A page of a query's rows and the token of the next page (`undefined`: the last). */
196
+ export interface QueryPage<T> {
197
+ rows: T[];
198
+ next?: string;
199
+ }
200
+ interface Tree {
201
+ sources: Record<string, unknown>[];
202
+ filter?: WExpr;
203
+ groupBy: WColumn[];
204
+ having?: WExpr;
205
+ select: Record<string, unknown>[];
206
+ order: {
207
+ term: WTerm;
208
+ desc: boolean;
209
+ }[];
210
+ limit: number;
211
+ }
212
+ declare class Sender {
213
+ readonly link: DbLink;
214
+ readonly tree: Tree;
215
+ readonly error: string | undefined;
216
+ readonly source: string;
217
+ constructor(link: DbLink, tree: Tree, error: string | undefined, source: string);
218
+ send(mode: string, token?: string): Promise<DbResult & {
219
+ dbRows?: DbResult["dbRows"];
220
+ }>;
221
+ rows(mode: string, token?: string): Promise<{
222
+ rows: unknown[];
223
+ next?: string;
224
+ }>;
225
+ count(): Promise<number>;
226
+ }
227
+ type StoredOf<R> = R extends EntityDef<any> ? Stored<R> : never;
228
+ /**
229
+ * A query over the root `Root`, the entities `J` (joined inner, the root among them) and `L` (joined left). Joins,
230
+ * `where`, `groupBy`, `having`, `orderBy` and `limit` build it; `select` names its rows' values; `all`, `first`,
231
+ * `count` and `page` read it. A dependency's entity keeps the repository's reads too (`get`, `find`, `exists`,
232
+ * `aggregate`).
233
+ */
234
+ export declare class Query<Root extends Queryable, J = RowOf<Root>, L = never> {
235
+ /** @internal */ readonly link: DbLink;
236
+ /** @internal */ readonly root: Root;
237
+ /** @internal */ readonly source: string;
238
+ /** @internal the repository of an entity root (its reads) */
239
+ readonly repo?: ReadRepository<any> | undefined;
240
+ /** @internal */ readonly tree: Tree;
241
+ /** @internal */ error?: string;
242
+ constructor(
243
+ /** @internal */ link: DbLink,
244
+ /** @internal */ root: Root,
245
+ /** @internal */ source: string,
246
+ /** @internal the repository of an entity root (its reads) */
247
+ repo?: ReadRepository<any> | undefined);
248
+ private fail;
249
+ /** The alias of the one source of `entity` (its default alias first). */
250
+ private sourceOf;
251
+ private addJoin;
252
+ private addJoinOn;
253
+ /** Joins `entity` along a ref between it and an entity of the query, either way. */
254
+ join<T extends Queryable>(entity: T, ref: JoinRefOf<T>): Query<Root, J | RowOf<T>, L>;
255
+ /** As `join`, keeping the rows that have no `entity` (or none the caller may read): its columns may be undefined. */
256
+ leftJoin<T extends Queryable>(entity: T, ref: JoinRefOf<T>): Query<Root, J, L | RowOf<T>>;
257
+ /** Joins `entity` on two columns of one entity's keys (`a.eqCol(b)`): one of `entity`, one of the query. */
258
+ joinOn<T extends Queryable>(entity: T, on: ColCmp): Query<Root, J | RowOf<T>, L>;
259
+ leftJoinOn<T extends Queryable>(entity: T, on: ColCmp): Query<Root, J, L | RowOf<T>>;
260
+ /** Joins an aliased entity (inner or left as the alias was made); its columns are the alias's (`a.f`). */
261
+ joinAs<T extends Queryable>(a: Alias<T, boolean>, ref: JoinRefOf<T>): this;
262
+ joinOnAs<T extends Queryable>(a: Alias<T, boolean>, on: ColCmp): this;
263
+ /** Keeps the rows for which every condition holds (several `where`s: all of them). */
264
+ where(...conds: CondIn<J | L>[]): this;
265
+ /** Groups the rows by these columns. */
266
+ groupBy(...columns: (ColumnIn<J | L> | AliasCol<any, any, any>)[]): this;
267
+ /** Keeps the groups for which every condition holds (aggregates and grouped columns). */
268
+ having(...conds: CondIn<J | L>[]): this;
269
+ /** Orders the rows (then by their keys). */
270
+ orderBy(...orders: OrderIn<J | L>[]): this;
271
+ /** At most `n` rows (a page: at most 100). */
272
+ limit(n: number): this;
273
+ /** The values of the rows, by name: columns, aggregates, labels. */
274
+ select<S extends Record<string, SelectItem<J | L>>>(items: S): Selected<{
275
+ [K in keyof S]: ItemValue<S[K], L>;
276
+ }>;
277
+ /** @internal */
278
+ sender(): Sender;
279
+ private plain;
280
+ /** The root's rows (at most 1,000: `query_rows_limit` past them). */
281
+ all(): Promise<StoredOf<Root>[]>;
282
+ /** The root's first row. */
283
+ first(): Promise<StoredOf<Root> | undefined>;
284
+ /** A page of the root's rows (`limit`, at most 100) after the token of the previous page. */
285
+ page(token?: string): Promise<QueryPage<StoredOf<Root>>>;
286
+ /** How many rows (or groups) the query has; with a filter of the root, those it matches. */
287
+ count(filter?: Filter<RowOf<Root>>): Promise<number>;
288
+ private decodeRoot;
289
+ private repository;
290
+ /** A row by id (the repository's read). */
291
+ get(id: string, options?: GetOptions): Promise<StoredOf<Root>>;
292
+ /** The rows matching `filter` (the repository's read): order, limit and page it. */
293
+ find(filter?: Filter<RowOf<Root>>): Root extends EntityDef<any> ? Find<Root> : never;
294
+ exists(filter: Filter<RowOf<Root>>): Promise<boolean>;
295
+ /** Groups of the rows (the repository's `aggregate`). */
296
+ get aggregate(): Root extends EntityDef<any> ? ReadRepository<Root>["aggregate"] : never;
297
+ }
298
+ /** A query whose rows are `T` (`select`): `orderBy` (by a select item's name too) and `limit` still apply. */
299
+ export declare class Selected<T> {
300
+ /** @internal */ readonly q: Sender;
301
+ /** @internal */ readonly read: Reader;
302
+ /** @internal */ readonly terms: Map<string, WTerm>;
303
+ constructor(
304
+ /** @internal */ q: Sender,
305
+ /** @internal */ read: Reader,
306
+ /** @internal */ terms: Map<string, WTerm>);
307
+ /** Orders the rows: by a select item (`{ revenue: 'desc' }`), a column or an aggregate; then by the keys. */
308
+ orderBy(...orders: (QOrder | Order<any> | {
309
+ [K in keyof T]?: "asc" | "desc";
310
+ })[]): this;
311
+ /** At most `n` rows (a page: at most 100). */
312
+ limit(n: number): this;
313
+ private decode;
314
+ /** Every row (at most 1,000, or `limit`: `query_rows_limit` past them). */
315
+ all(): Promise<T[]>;
316
+ first(): Promise<T | undefined>;
317
+ /** A page (`limit`, at most 100) after the token of the previous page: keyset over the order and the keys. */
318
+ page(token?: string): Promise<QueryPage<T>>;
319
+ /** How many rows (or groups). */
320
+ count(): Promise<number>;
321
+ /** The query tree the SDK sends (`celobus.v1.Query`), in the protobuf JSON mapping. */
322
+ tree(): Record<string, unknown>;
323
+ }
324
+ /** @internal The start of a query (`ctx.query`). */
325
+ export declare function startQuery<E extends Queryable>(link: DbLink, entity: E): Query<E>;
326
+ export {};