@colspec/core 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.
- package/LICENSE +22 -0
- package/README.md +90 -2
- package/dist/contract.schema.json +469 -0
- package/dist/index.d.mts +306 -0
- package/dist/index.mjs +305 -0
- package/package.json +48 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Om Prakash Das
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
package/README.md
CHANGED
|
@@ -1,3 +1,91 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @colspec/core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The contract at the center of [colspec](https://github.com/Om1938/colspec):
|
|
4
|
+
a JSON format for TanStack Table definitions, with validation and the registry
|
|
5
|
+
types that connect names in the JSON to functions in your code.
|
|
6
|
+
|
|
7
|
+
It has no dependency on React, TanStack Table or any database, so it runs in
|
|
8
|
+
the browser and on the server.
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
npm install @colspec/core
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Validate a contract
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import { validateContract } from "@colspec/core";
|
|
18
|
+
|
|
19
|
+
const result = validateContract(json);
|
|
20
|
+
|
|
21
|
+
if (result.ok) {
|
|
22
|
+
result.value; // a typed TableContract
|
|
23
|
+
} else {
|
|
24
|
+
result.diagnostics; // [{ code, severity, path, message }]
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
A contract looks like this. Property names follow TanStack Table v9; anything
|
|
29
|
+
executable is a named reference.
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"schemaVersion": "1.0",
|
|
34
|
+
"tableId": "crm.contacts",
|
|
35
|
+
"revision": 4,
|
|
36
|
+
"columns": [
|
|
37
|
+
{
|
|
38
|
+
"id": "name",
|
|
39
|
+
"accessorKey": "name",
|
|
40
|
+
"header": "Name",
|
|
41
|
+
"sortFn": "alphanumeric"
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
"id": "status",
|
|
45
|
+
"accessorKey": "status",
|
|
46
|
+
"cell": { "ref": "crm.statusBadge" }
|
|
47
|
+
}
|
|
48
|
+
],
|
|
49
|
+
"defaults": { "pagination": { "pageSize": 25 } },
|
|
50
|
+
"mode": { "sorting": "client", "filtering": "client", "pagination": "server" }
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Validation covers structure, schema version, duplicate column ids, defaults
|
|
55
|
+
that name unknown columns, and execution modes that don't work together. Add
|
|
56
|
+
your own checks with `validateContract(json, { rules })`.
|
|
57
|
+
|
|
58
|
+
## Compose registries
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import { composeRegistries } from "@colspec/core";
|
|
62
|
+
|
|
63
|
+
const registry = composeRegistries([crmRegistry, billingRegistry]);
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
A name registered twice throws unless you pass `{ onCollision: "override" }`.
|
|
67
|
+
|
|
68
|
+
## Send table state to your API
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
import { toServerQuery } from "@colspec/core";
|
|
72
|
+
|
|
73
|
+
toServerQuery(contract, { sorting, columnFilters, pagination });
|
|
74
|
+
// { sort: [{ key: "contact.created_at", desc: true }], page: { index: 0, size: 25 } }
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Only the operations the contract runs on the server are included.
|
|
78
|
+
|
|
79
|
+
## JSON Schema
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import schema from "@colspec/core/contract.schema.json" with { type: "json" };
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Related packages
|
|
86
|
+
|
|
87
|
+
- [`@colspec/tanstack`](https://www.npmjs.com/package/@colspec/tanstack): turn a contract into column definitions
|
|
88
|
+
- [`@colspec/react`](https://www.npmjs.com/package/@colspec/react): React hooks
|
|
89
|
+
- [`@colspec/server`](https://www.npmjs.com/package/@colspec/server): store and serve contracts
|
|
90
|
+
|
|
91
|
+
[Documentation](https://github.com/Om1938/colspec/tree/main/apps/docs/guide) · MIT
|
|
@@ -0,0 +1,469 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"type": "object",
|
|
4
|
+
"properties": {
|
|
5
|
+
"schemaVersion": {
|
|
6
|
+
"type": "string",
|
|
7
|
+
"pattern": "^\\d+\\.\\d+$"
|
|
8
|
+
},
|
|
9
|
+
"tableId": {
|
|
10
|
+
"type": "string",
|
|
11
|
+
"minLength": 1
|
|
12
|
+
},
|
|
13
|
+
"revision": {
|
|
14
|
+
"type": "integer",
|
|
15
|
+
"exclusiveMinimum": 0,
|
|
16
|
+
"maximum": 9007199254740991
|
|
17
|
+
},
|
|
18
|
+
"columns": {
|
|
19
|
+
"minItems": 1,
|
|
20
|
+
"type": "array",
|
|
21
|
+
"items": {
|
|
22
|
+
"type": "object",
|
|
23
|
+
"properties": {
|
|
24
|
+
"id": {
|
|
25
|
+
"type": "string",
|
|
26
|
+
"minLength": 1
|
|
27
|
+
},
|
|
28
|
+
"accessorKey": {
|
|
29
|
+
"type": "string",
|
|
30
|
+
"minLength": 1
|
|
31
|
+
},
|
|
32
|
+
"accessorFn": {
|
|
33
|
+
"type": "object",
|
|
34
|
+
"properties": {
|
|
35
|
+
"ref": {
|
|
36
|
+
"type": "string",
|
|
37
|
+
"minLength": 1
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
"required": [
|
|
41
|
+
"ref"
|
|
42
|
+
],
|
|
43
|
+
"additionalProperties": false
|
|
44
|
+
},
|
|
45
|
+
"header": {
|
|
46
|
+
"anyOf": [
|
|
47
|
+
{
|
|
48
|
+
"type": "string"
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
"type": "object",
|
|
52
|
+
"properties": {
|
|
53
|
+
"ref": {
|
|
54
|
+
"type": "string",
|
|
55
|
+
"minLength": 1
|
|
56
|
+
}
|
|
57
|
+
},
|
|
58
|
+
"required": [
|
|
59
|
+
"ref"
|
|
60
|
+
],
|
|
61
|
+
"additionalProperties": false
|
|
62
|
+
}
|
|
63
|
+
]
|
|
64
|
+
},
|
|
65
|
+
"footer": {
|
|
66
|
+
"anyOf": [
|
|
67
|
+
{
|
|
68
|
+
"type": "string"
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"type": "object",
|
|
72
|
+
"properties": {
|
|
73
|
+
"ref": {
|
|
74
|
+
"type": "string",
|
|
75
|
+
"minLength": 1
|
|
76
|
+
}
|
|
77
|
+
},
|
|
78
|
+
"required": [
|
|
79
|
+
"ref"
|
|
80
|
+
],
|
|
81
|
+
"additionalProperties": false
|
|
82
|
+
}
|
|
83
|
+
]
|
|
84
|
+
},
|
|
85
|
+
"cell": {
|
|
86
|
+
"type": "object",
|
|
87
|
+
"properties": {
|
|
88
|
+
"ref": {
|
|
89
|
+
"type": "string",
|
|
90
|
+
"minLength": 1
|
|
91
|
+
}
|
|
92
|
+
},
|
|
93
|
+
"required": [
|
|
94
|
+
"ref"
|
|
95
|
+
],
|
|
96
|
+
"additionalProperties": false
|
|
97
|
+
},
|
|
98
|
+
"formatter": {
|
|
99
|
+
"type": "object",
|
|
100
|
+
"properties": {
|
|
101
|
+
"ref": {
|
|
102
|
+
"type": "string",
|
|
103
|
+
"minLength": 1
|
|
104
|
+
}
|
|
105
|
+
},
|
|
106
|
+
"required": [
|
|
107
|
+
"ref"
|
|
108
|
+
],
|
|
109
|
+
"additionalProperties": false
|
|
110
|
+
},
|
|
111
|
+
"actions": {
|
|
112
|
+
"type": "array",
|
|
113
|
+
"items": {
|
|
114
|
+
"type": "object",
|
|
115
|
+
"properties": {
|
|
116
|
+
"ref": {
|
|
117
|
+
"type": "string",
|
|
118
|
+
"minLength": 1
|
|
119
|
+
}
|
|
120
|
+
},
|
|
121
|
+
"required": [
|
|
122
|
+
"ref"
|
|
123
|
+
],
|
|
124
|
+
"additionalProperties": false
|
|
125
|
+
}
|
|
126
|
+
},
|
|
127
|
+
"sortFn": {
|
|
128
|
+
"anyOf": [
|
|
129
|
+
{
|
|
130
|
+
"type": "string",
|
|
131
|
+
"minLength": 1
|
|
132
|
+
},
|
|
133
|
+
{
|
|
134
|
+
"type": "object",
|
|
135
|
+
"properties": {
|
|
136
|
+
"ref": {
|
|
137
|
+
"type": "string",
|
|
138
|
+
"minLength": 1
|
|
139
|
+
}
|
|
140
|
+
},
|
|
141
|
+
"required": [
|
|
142
|
+
"ref"
|
|
143
|
+
],
|
|
144
|
+
"additionalProperties": false
|
|
145
|
+
}
|
|
146
|
+
]
|
|
147
|
+
},
|
|
148
|
+
"filterFn": {
|
|
149
|
+
"anyOf": [
|
|
150
|
+
{
|
|
151
|
+
"type": "string",
|
|
152
|
+
"minLength": 1
|
|
153
|
+
},
|
|
154
|
+
{
|
|
155
|
+
"type": "object",
|
|
156
|
+
"properties": {
|
|
157
|
+
"ref": {
|
|
158
|
+
"type": "string",
|
|
159
|
+
"minLength": 1
|
|
160
|
+
}
|
|
161
|
+
},
|
|
162
|
+
"required": [
|
|
163
|
+
"ref"
|
|
164
|
+
],
|
|
165
|
+
"additionalProperties": false
|
|
166
|
+
}
|
|
167
|
+
]
|
|
168
|
+
},
|
|
169
|
+
"aggregationFn": {
|
|
170
|
+
"anyOf": [
|
|
171
|
+
{
|
|
172
|
+
"type": "string",
|
|
173
|
+
"minLength": 1
|
|
174
|
+
},
|
|
175
|
+
{
|
|
176
|
+
"type": "object",
|
|
177
|
+
"properties": {
|
|
178
|
+
"ref": {
|
|
179
|
+
"type": "string",
|
|
180
|
+
"minLength": 1
|
|
181
|
+
}
|
|
182
|
+
},
|
|
183
|
+
"required": [
|
|
184
|
+
"ref"
|
|
185
|
+
],
|
|
186
|
+
"additionalProperties": false
|
|
187
|
+
}
|
|
188
|
+
]
|
|
189
|
+
},
|
|
190
|
+
"enableSorting": {
|
|
191
|
+
"type": "boolean"
|
|
192
|
+
},
|
|
193
|
+
"enableMultiSort": {
|
|
194
|
+
"type": "boolean"
|
|
195
|
+
},
|
|
196
|
+
"invertSorting": {
|
|
197
|
+
"type": "boolean"
|
|
198
|
+
},
|
|
199
|
+
"sortDescFirst": {
|
|
200
|
+
"type": "boolean"
|
|
201
|
+
},
|
|
202
|
+
"sortUndefined": {
|
|
203
|
+
"anyOf": [
|
|
204
|
+
{
|
|
205
|
+
"type": "boolean",
|
|
206
|
+
"const": false
|
|
207
|
+
},
|
|
208
|
+
{
|
|
209
|
+
"type": "number",
|
|
210
|
+
"const": -1
|
|
211
|
+
},
|
|
212
|
+
{
|
|
213
|
+
"type": "number",
|
|
214
|
+
"const": 1
|
|
215
|
+
},
|
|
216
|
+
{
|
|
217
|
+
"type": "string",
|
|
218
|
+
"enum": [
|
|
219
|
+
"first",
|
|
220
|
+
"last"
|
|
221
|
+
]
|
|
222
|
+
}
|
|
223
|
+
]
|
|
224
|
+
},
|
|
225
|
+
"enableColumnFilter": {
|
|
226
|
+
"type": "boolean"
|
|
227
|
+
},
|
|
228
|
+
"enableGlobalFilter": {
|
|
229
|
+
"type": "boolean"
|
|
230
|
+
},
|
|
231
|
+
"enableHiding": {
|
|
232
|
+
"type": "boolean"
|
|
233
|
+
},
|
|
234
|
+
"enableGrouping": {
|
|
235
|
+
"type": "boolean"
|
|
236
|
+
},
|
|
237
|
+
"enablePinning": {
|
|
238
|
+
"type": "boolean"
|
|
239
|
+
},
|
|
240
|
+
"enableResizing": {
|
|
241
|
+
"type": "boolean"
|
|
242
|
+
},
|
|
243
|
+
"size": {
|
|
244
|
+
"type": "number",
|
|
245
|
+
"minimum": 0
|
|
246
|
+
},
|
|
247
|
+
"minSize": {
|
|
248
|
+
"type": "number",
|
|
249
|
+
"minimum": 0
|
|
250
|
+
},
|
|
251
|
+
"maxSize": {
|
|
252
|
+
"type": "number",
|
|
253
|
+
"minimum": 0
|
|
254
|
+
},
|
|
255
|
+
"server": {
|
|
256
|
+
"type": "object",
|
|
257
|
+
"properties": {
|
|
258
|
+
"sortKey": {
|
|
259
|
+
"type": "string",
|
|
260
|
+
"minLength": 1
|
|
261
|
+
},
|
|
262
|
+
"filterKey": {
|
|
263
|
+
"type": "string",
|
|
264
|
+
"minLength": 1
|
|
265
|
+
}
|
|
266
|
+
},
|
|
267
|
+
"additionalProperties": false
|
|
268
|
+
},
|
|
269
|
+
"meta": {
|
|
270
|
+
"type": "object",
|
|
271
|
+
"propertyNames": {
|
|
272
|
+
"type": "string"
|
|
273
|
+
},
|
|
274
|
+
"additionalProperties": {
|
|
275
|
+
"$ref": "#/$defs/__schema0"
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
},
|
|
279
|
+
"required": [
|
|
280
|
+
"id"
|
|
281
|
+
],
|
|
282
|
+
"additionalProperties": false
|
|
283
|
+
}
|
|
284
|
+
},
|
|
285
|
+
"defaults": {
|
|
286
|
+
"type": "object",
|
|
287
|
+
"properties": {
|
|
288
|
+
"sorting": {
|
|
289
|
+
"type": "array",
|
|
290
|
+
"items": {
|
|
291
|
+
"type": "object",
|
|
292
|
+
"properties": {
|
|
293
|
+
"id": {
|
|
294
|
+
"type": "string"
|
|
295
|
+
},
|
|
296
|
+
"desc": {
|
|
297
|
+
"type": "boolean"
|
|
298
|
+
}
|
|
299
|
+
},
|
|
300
|
+
"required": [
|
|
301
|
+
"id",
|
|
302
|
+
"desc"
|
|
303
|
+
],
|
|
304
|
+
"additionalProperties": false
|
|
305
|
+
}
|
|
306
|
+
},
|
|
307
|
+
"columnFilters": {
|
|
308
|
+
"type": "array",
|
|
309
|
+
"items": {
|
|
310
|
+
"type": "object",
|
|
311
|
+
"properties": {
|
|
312
|
+
"id": {
|
|
313
|
+
"type": "string"
|
|
314
|
+
},
|
|
315
|
+
"value": {
|
|
316
|
+
"$ref": "#/$defs/__schema1"
|
|
317
|
+
}
|
|
318
|
+
},
|
|
319
|
+
"required": [
|
|
320
|
+
"id",
|
|
321
|
+
"value"
|
|
322
|
+
],
|
|
323
|
+
"additionalProperties": false
|
|
324
|
+
}
|
|
325
|
+
},
|
|
326
|
+
"pagination": {
|
|
327
|
+
"type": "object",
|
|
328
|
+
"properties": {
|
|
329
|
+
"pageIndex": {
|
|
330
|
+
"default": 0,
|
|
331
|
+
"type": "integer",
|
|
332
|
+
"minimum": 0,
|
|
333
|
+
"maximum": 9007199254740991
|
|
334
|
+
},
|
|
335
|
+
"pageSize": {
|
|
336
|
+
"type": "integer",
|
|
337
|
+
"exclusiveMinimum": 0,
|
|
338
|
+
"maximum": 9007199254740991
|
|
339
|
+
}
|
|
340
|
+
},
|
|
341
|
+
"required": [
|
|
342
|
+
"pageSize"
|
|
343
|
+
],
|
|
344
|
+
"additionalProperties": false
|
|
345
|
+
},
|
|
346
|
+
"columnVisibility": {
|
|
347
|
+
"type": "object",
|
|
348
|
+
"propertyNames": {
|
|
349
|
+
"type": "string"
|
|
350
|
+
},
|
|
351
|
+
"additionalProperties": {
|
|
352
|
+
"type": "boolean"
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
},
|
|
356
|
+
"additionalProperties": false
|
|
357
|
+
},
|
|
358
|
+
"mode": {
|
|
359
|
+
"type": "object",
|
|
360
|
+
"properties": {
|
|
361
|
+
"sorting": {
|
|
362
|
+
"default": "client",
|
|
363
|
+
"type": "string",
|
|
364
|
+
"enum": [
|
|
365
|
+
"client",
|
|
366
|
+
"server"
|
|
367
|
+
]
|
|
368
|
+
},
|
|
369
|
+
"filtering": {
|
|
370
|
+
"default": "client",
|
|
371
|
+
"type": "string",
|
|
372
|
+
"enum": [
|
|
373
|
+
"client",
|
|
374
|
+
"server"
|
|
375
|
+
]
|
|
376
|
+
},
|
|
377
|
+
"pagination": {
|
|
378
|
+
"default": "client",
|
|
379
|
+
"type": "string",
|
|
380
|
+
"enum": [
|
|
381
|
+
"client",
|
|
382
|
+
"server"
|
|
383
|
+
]
|
|
384
|
+
}
|
|
385
|
+
},
|
|
386
|
+
"additionalProperties": false
|
|
387
|
+
},
|
|
388
|
+
"meta": {
|
|
389
|
+
"type": "object",
|
|
390
|
+
"propertyNames": {
|
|
391
|
+
"type": "string"
|
|
392
|
+
},
|
|
393
|
+
"additionalProperties": {
|
|
394
|
+
"$ref": "#/$defs/__schema0"
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
},
|
|
398
|
+
"required": [
|
|
399
|
+
"schemaVersion",
|
|
400
|
+
"tableId",
|
|
401
|
+
"revision",
|
|
402
|
+
"columns"
|
|
403
|
+
],
|
|
404
|
+
"additionalProperties": false,
|
|
405
|
+
"$defs": {
|
|
406
|
+
"__schema0": {
|
|
407
|
+
"anyOf": [
|
|
408
|
+
{
|
|
409
|
+
"type": "string"
|
|
410
|
+
},
|
|
411
|
+
{
|
|
412
|
+
"type": "number"
|
|
413
|
+
},
|
|
414
|
+
{
|
|
415
|
+
"type": "boolean"
|
|
416
|
+
},
|
|
417
|
+
{
|
|
418
|
+
"type": "null"
|
|
419
|
+
},
|
|
420
|
+
{
|
|
421
|
+
"type": "array",
|
|
422
|
+
"items": {
|
|
423
|
+
"$ref": "#/$defs/__schema0"
|
|
424
|
+
}
|
|
425
|
+
},
|
|
426
|
+
{
|
|
427
|
+
"type": "object",
|
|
428
|
+
"propertyNames": {
|
|
429
|
+
"type": "string"
|
|
430
|
+
},
|
|
431
|
+
"additionalProperties": {
|
|
432
|
+
"$ref": "#/$defs/__schema0"
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
]
|
|
436
|
+
},
|
|
437
|
+
"__schema1": {
|
|
438
|
+
"anyOf": [
|
|
439
|
+
{
|
|
440
|
+
"type": "string"
|
|
441
|
+
},
|
|
442
|
+
{
|
|
443
|
+
"type": "number"
|
|
444
|
+
},
|
|
445
|
+
{
|
|
446
|
+
"type": "boolean"
|
|
447
|
+
},
|
|
448
|
+
{
|
|
449
|
+
"type": "null"
|
|
450
|
+
},
|
|
451
|
+
{
|
|
452
|
+
"type": "array",
|
|
453
|
+
"items": {
|
|
454
|
+
"$ref": "#/$defs/__schema1"
|
|
455
|
+
}
|
|
456
|
+
},
|
|
457
|
+
{
|
|
458
|
+
"type": "object",
|
|
459
|
+
"propertyNames": {
|
|
460
|
+
"type": "string"
|
|
461
|
+
},
|
|
462
|
+
"additionalProperties": {
|
|
463
|
+
"$ref": "#/$defs/__schema1"
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
]
|
|
467
|
+
}
|
|
468
|
+
}
|
|
469
|
+
}
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
//#region src/contract.d.ts
|
|
3
|
+
declare const executionSchema: z.ZodEnum<{
|
|
4
|
+
server: "server";
|
|
5
|
+
client: "client";
|
|
6
|
+
}>;
|
|
7
|
+
export declare const columnSchema: z.ZodObject<{
|
|
8
|
+
id: z.ZodString;
|
|
9
|
+
accessorKey: z.ZodOptional<z.ZodString>;
|
|
10
|
+
accessorFn: z.ZodOptional<z.ZodObject<{
|
|
11
|
+
ref: z.ZodString;
|
|
12
|
+
}, z.core.$strict>>;
|
|
13
|
+
header: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
14
|
+
ref: z.ZodString;
|
|
15
|
+
}, z.core.$strict>]>>;
|
|
16
|
+
footer: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
17
|
+
ref: z.ZodString;
|
|
18
|
+
}, z.core.$strict>]>>;
|
|
19
|
+
cell: z.ZodOptional<z.ZodObject<{
|
|
20
|
+
ref: z.ZodString;
|
|
21
|
+
}, z.core.$strict>>;
|
|
22
|
+
formatter: z.ZodOptional<z.ZodObject<{
|
|
23
|
+
ref: z.ZodString;
|
|
24
|
+
}, z.core.$strict>>;
|
|
25
|
+
actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
26
|
+
ref: z.ZodString;
|
|
27
|
+
}, z.core.$strict>>>;
|
|
28
|
+
sortFn: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
29
|
+
ref: z.ZodString;
|
|
30
|
+
}, z.core.$strict>]>>;
|
|
31
|
+
filterFn: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
32
|
+
ref: z.ZodString;
|
|
33
|
+
}, z.core.$strict>]>>;
|
|
34
|
+
aggregationFn: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
35
|
+
ref: z.ZodString;
|
|
36
|
+
}, z.core.$strict>]>>;
|
|
37
|
+
enableSorting: z.ZodOptional<z.ZodBoolean>;
|
|
38
|
+
enableMultiSort: z.ZodOptional<z.ZodBoolean>;
|
|
39
|
+
invertSorting: z.ZodOptional<z.ZodBoolean>;
|
|
40
|
+
sortDescFirst: z.ZodOptional<z.ZodBoolean>;
|
|
41
|
+
sortUndefined: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodLiteral<-1>, z.ZodLiteral<1>, z.ZodEnum<{
|
|
42
|
+
first: "first";
|
|
43
|
+
last: "last";
|
|
44
|
+
}>]>>;
|
|
45
|
+
enableColumnFilter: z.ZodOptional<z.ZodBoolean>;
|
|
46
|
+
enableGlobalFilter: z.ZodOptional<z.ZodBoolean>;
|
|
47
|
+
enableHiding: z.ZodOptional<z.ZodBoolean>;
|
|
48
|
+
enableGrouping: z.ZodOptional<z.ZodBoolean>;
|
|
49
|
+
enablePinning: z.ZodOptional<z.ZodBoolean>;
|
|
50
|
+
enableResizing: z.ZodOptional<z.ZodBoolean>;
|
|
51
|
+
size: z.ZodOptional<z.ZodNumber>;
|
|
52
|
+
minSize: z.ZodOptional<z.ZodNumber>;
|
|
53
|
+
maxSize: z.ZodOptional<z.ZodNumber>;
|
|
54
|
+
server: z.ZodOptional<z.ZodObject<{
|
|
55
|
+
sortKey: z.ZodOptional<z.ZodString>;
|
|
56
|
+
filterKey: z.ZodOptional<z.ZodString>;
|
|
57
|
+
}, z.core.$strict>>;
|
|
58
|
+
meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
|
|
59
|
+
}, z.core.$strict>;
|
|
60
|
+
export declare const defaultsSchema: z.ZodObject<{
|
|
61
|
+
sorting: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
62
|
+
id: z.ZodString;
|
|
63
|
+
desc: z.ZodBoolean;
|
|
64
|
+
}, z.core.$strict>>>;
|
|
65
|
+
columnFilters: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
66
|
+
id: z.ZodString;
|
|
67
|
+
value: z.ZodJSONSchema;
|
|
68
|
+
}, z.core.$strict>>>;
|
|
69
|
+
pagination: z.ZodOptional<z.ZodObject<{
|
|
70
|
+
pageIndex: z.ZodDefault<z.ZodNumber>;
|
|
71
|
+
pageSize: z.ZodNumber;
|
|
72
|
+
}, z.core.$strict>>;
|
|
73
|
+
columnVisibility: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
|
|
74
|
+
}, z.core.$strict>;
|
|
75
|
+
export declare const modeSchema: z.ZodObject<{
|
|
76
|
+
sorting: z.ZodDefault<z.ZodEnum<{
|
|
77
|
+
server: "server";
|
|
78
|
+
client: "client";
|
|
79
|
+
}>>;
|
|
80
|
+
filtering: z.ZodDefault<z.ZodEnum<{
|
|
81
|
+
server: "server";
|
|
82
|
+
client: "client";
|
|
83
|
+
}>>;
|
|
84
|
+
pagination: z.ZodDefault<z.ZodEnum<{
|
|
85
|
+
server: "server";
|
|
86
|
+
client: "client";
|
|
87
|
+
}>>;
|
|
88
|
+
}, z.core.$strict>;
|
|
89
|
+
export declare const tableContractSchema: z.ZodObject<{
|
|
90
|
+
schemaVersion: z.ZodString;
|
|
91
|
+
tableId: z.ZodString;
|
|
92
|
+
revision: z.ZodNumber;
|
|
93
|
+
columns: z.ZodArray<z.ZodObject<{
|
|
94
|
+
id: z.ZodString;
|
|
95
|
+
accessorKey: z.ZodOptional<z.ZodString>;
|
|
96
|
+
accessorFn: z.ZodOptional<z.ZodObject<{
|
|
97
|
+
ref: z.ZodString;
|
|
98
|
+
}, z.core.$strict>>;
|
|
99
|
+
header: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
100
|
+
ref: z.ZodString;
|
|
101
|
+
}, z.core.$strict>]>>;
|
|
102
|
+
footer: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
103
|
+
ref: z.ZodString;
|
|
104
|
+
}, z.core.$strict>]>>;
|
|
105
|
+
cell: z.ZodOptional<z.ZodObject<{
|
|
106
|
+
ref: z.ZodString;
|
|
107
|
+
}, z.core.$strict>>;
|
|
108
|
+
formatter: z.ZodOptional<z.ZodObject<{
|
|
109
|
+
ref: z.ZodString;
|
|
110
|
+
}, z.core.$strict>>;
|
|
111
|
+
actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
112
|
+
ref: z.ZodString;
|
|
113
|
+
}, z.core.$strict>>>;
|
|
114
|
+
sortFn: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
115
|
+
ref: z.ZodString;
|
|
116
|
+
}, z.core.$strict>]>>;
|
|
117
|
+
filterFn: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
118
|
+
ref: z.ZodString;
|
|
119
|
+
}, z.core.$strict>]>>;
|
|
120
|
+
aggregationFn: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
121
|
+
ref: z.ZodString;
|
|
122
|
+
}, z.core.$strict>]>>;
|
|
123
|
+
enableSorting: z.ZodOptional<z.ZodBoolean>;
|
|
124
|
+
enableMultiSort: z.ZodOptional<z.ZodBoolean>;
|
|
125
|
+
invertSorting: z.ZodOptional<z.ZodBoolean>;
|
|
126
|
+
sortDescFirst: z.ZodOptional<z.ZodBoolean>;
|
|
127
|
+
sortUndefined: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodLiteral<-1>, z.ZodLiteral<1>, z.ZodEnum<{
|
|
128
|
+
first: "first";
|
|
129
|
+
last: "last";
|
|
130
|
+
}>]>>;
|
|
131
|
+
enableColumnFilter: z.ZodOptional<z.ZodBoolean>;
|
|
132
|
+
enableGlobalFilter: z.ZodOptional<z.ZodBoolean>;
|
|
133
|
+
enableHiding: z.ZodOptional<z.ZodBoolean>;
|
|
134
|
+
enableGrouping: z.ZodOptional<z.ZodBoolean>;
|
|
135
|
+
enablePinning: z.ZodOptional<z.ZodBoolean>;
|
|
136
|
+
enableResizing: z.ZodOptional<z.ZodBoolean>;
|
|
137
|
+
size: z.ZodOptional<z.ZodNumber>;
|
|
138
|
+
minSize: z.ZodOptional<z.ZodNumber>;
|
|
139
|
+
maxSize: z.ZodOptional<z.ZodNumber>;
|
|
140
|
+
server: z.ZodOptional<z.ZodObject<{
|
|
141
|
+
sortKey: z.ZodOptional<z.ZodString>;
|
|
142
|
+
filterKey: z.ZodOptional<z.ZodString>;
|
|
143
|
+
}, z.core.$strict>>;
|
|
144
|
+
meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
|
|
145
|
+
}, z.core.$strict>>;
|
|
146
|
+
defaults: z.ZodOptional<z.ZodObject<{
|
|
147
|
+
sorting: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
148
|
+
id: z.ZodString;
|
|
149
|
+
desc: z.ZodBoolean;
|
|
150
|
+
}, z.core.$strict>>>;
|
|
151
|
+
columnFilters: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
152
|
+
id: z.ZodString;
|
|
153
|
+
value: z.ZodJSONSchema;
|
|
154
|
+
}, z.core.$strict>>>;
|
|
155
|
+
pagination: z.ZodOptional<z.ZodObject<{
|
|
156
|
+
pageIndex: z.ZodDefault<z.ZodNumber>;
|
|
157
|
+
pageSize: z.ZodNumber;
|
|
158
|
+
}, z.core.$strict>>;
|
|
159
|
+
columnVisibility: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
|
|
160
|
+
}, z.core.$strict>>;
|
|
161
|
+
mode: z.ZodOptional<z.ZodObject<{
|
|
162
|
+
sorting: z.ZodDefault<z.ZodEnum<{
|
|
163
|
+
server: "server";
|
|
164
|
+
client: "client";
|
|
165
|
+
}>>;
|
|
166
|
+
filtering: z.ZodDefault<z.ZodEnum<{
|
|
167
|
+
server: "server";
|
|
168
|
+
client: "client";
|
|
169
|
+
}>>;
|
|
170
|
+
pagination: z.ZodDefault<z.ZodEnum<{
|
|
171
|
+
server: "server";
|
|
172
|
+
client: "client";
|
|
173
|
+
}>>;
|
|
174
|
+
}, z.core.$strict>>;
|
|
175
|
+
meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
|
|
176
|
+
}, z.core.$strict>;
|
|
177
|
+
export type ContractColumn = z.infer<typeof columnSchema>;
|
|
178
|
+
export type ContractDefaults = z.infer<typeof defaultsSchema>;
|
|
179
|
+
export type ContractMode = z.infer<typeof modeSchema>;
|
|
180
|
+
export type ExecutionMode = z.infer<typeof executionSchema>;
|
|
181
|
+
export type TableContract = z.infer<typeof tableContractSchema>;
|
|
182
|
+
/** The contract's execution modes with client-side defaults applied. */
|
|
183
|
+
export declare function getMode(contract: TableContract): ContractMode;
|
|
184
|
+
//#endregion
|
|
185
|
+
//#region src/diagnostics.d.ts
|
|
186
|
+
export type Severity = "error" | "warning";
|
|
187
|
+
export interface Diagnostic {
|
|
188
|
+
code: string;
|
|
189
|
+
severity: Severity;
|
|
190
|
+
/** Location inside the contract, e.g. `["columns", 2, "sortFn"]`. */
|
|
191
|
+
path: ReadonlyArray<string | number>;
|
|
192
|
+
message: string;
|
|
193
|
+
}
|
|
194
|
+
export type Result<T> = {
|
|
195
|
+
ok: true;
|
|
196
|
+
value: T;
|
|
197
|
+
diagnostics: Diagnostic[];
|
|
198
|
+
} | {
|
|
199
|
+
ok: false;
|
|
200
|
+
diagnostics: Diagnostic[];
|
|
201
|
+
};
|
|
202
|
+
export declare function hasErrors(diagnostics: ReadonlyArray<Diagnostic>): boolean;
|
|
203
|
+
/** Converts schema validation issues into error diagnostics under one code. */
|
|
204
|
+
export declare function issuesToDiagnostics(issues: ReadonlyArray<{
|
|
205
|
+
path: ReadonlyArray<PropertyKey>;
|
|
206
|
+
message: string;
|
|
207
|
+
}>, code: string): Diagnostic[];
|
|
208
|
+
/** A value is only usable when none of its diagnostics are errors. */
|
|
209
|
+
export declare function toResult<T>(value: T, diagnostics: Diagnostic[]): Result<T>;
|
|
210
|
+
/** Thrown where a failed `Result` cannot be returned to the caller. */
|
|
211
|
+
export declare class ContractError extends Error {
|
|
212
|
+
readonly diagnostics: ReadonlyArray<Diagnostic>;
|
|
213
|
+
constructor(diagnostics: ReadonlyArray<Diagnostic>);
|
|
214
|
+
}
|
|
215
|
+
//#endregion
|
|
216
|
+
//#region src/ref.d.ts
|
|
217
|
+
/** A named reference to a function the consuming application registers. */
|
|
218
|
+
export declare const refSchema: z.ZodObject<{
|
|
219
|
+
ref: z.ZodString;
|
|
220
|
+
}, z.core.$strict>;
|
|
221
|
+
export type Ref = z.infer<typeof refSchema>;
|
|
222
|
+
export declare function isRef(value: unknown): value is Ref;
|
|
223
|
+
//#endregion
|
|
224
|
+
//#region src/registry.d.ts
|
|
225
|
+
export declare const REGISTRY_CATEGORIES: readonly ["sortFns", "filterFns", "accessorFns", "cells", "headers", "formatters", "actions", "aggregationFns"];
|
|
226
|
+
export type RegistryCategory = (typeof REGISTRY_CATEGORIES)[number];
|
|
227
|
+
type EntryTypes = Record<RegistryCategory, unknown>;
|
|
228
|
+
/**
|
|
229
|
+
* Named functions an application makes available to contracts. Adapters fix
|
|
230
|
+
* `TEntries` to the function types their table engine expects.
|
|
231
|
+
*/
|
|
232
|
+
export type Registry<TEntries extends EntryTypes = EntryTypes> = { readonly [K in RegistryCategory]: Readonly<Record<string, TEntries[K]>>; };
|
|
233
|
+
export type RegistryInput<TEntries extends EntryTypes = EntryTypes> = Partial<Registry<TEntries>>;
|
|
234
|
+
export declare class RegistryCollisionError extends Error {
|
|
235
|
+
constructor(category: RegistryCategory, name: string);
|
|
236
|
+
}
|
|
237
|
+
export interface ComposeOptions {
|
|
238
|
+
/** `error` (default) rejects duplicate names; `override` lets later registries win. */
|
|
239
|
+
onCollision?: "error" | "override";
|
|
240
|
+
}
|
|
241
|
+
/** Merges registries contributed by separate application modules. */
|
|
242
|
+
export declare function composeRegistries<TEntries extends EntryTypes = EntryTypes>(registries: ReadonlyArray<RegistryInput<TEntries>>, { onCollision }?: ComposeOptions): Registry<TEntries>;
|
|
243
|
+
/** Creates a complete, immutable registry from the categories provided. */
|
|
244
|
+
export declare function createRegistry<TEntries extends EntryTypes = EntryTypes>(input?: RegistryInput<TEntries>): Registry<TEntries>;
|
|
245
|
+
//#endregion
|
|
246
|
+
//#region src/rules.d.ts
|
|
247
|
+
/** A semantic check that the JSON structure alone cannot express. */
|
|
248
|
+
export type ContractRule = (contract: TableContract) => Diagnostic[];
|
|
249
|
+
export declare const contractRules: ReadonlyArray<ContractRule>;
|
|
250
|
+
//#endregion
|
|
251
|
+
//#region src/server-query.d.ts
|
|
252
|
+
/** The slices of table state that server-side operations depend on. */
|
|
253
|
+
export interface QueryState {
|
|
254
|
+
sorting?: ReadonlyArray<{
|
|
255
|
+
id: string;
|
|
256
|
+
desc: boolean;
|
|
257
|
+
}>;
|
|
258
|
+
columnFilters?: ReadonlyArray<{
|
|
259
|
+
id: string;
|
|
260
|
+
value: unknown;
|
|
261
|
+
}>;
|
|
262
|
+
pagination?: {
|
|
263
|
+
pageIndex: number;
|
|
264
|
+
pageSize: number;
|
|
265
|
+
};
|
|
266
|
+
}
|
|
267
|
+
/** What the data API receives: operation keys instead of column ids. */
|
|
268
|
+
export declare const serverQuerySchema: z.ZodObject<{
|
|
269
|
+
sort: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
270
|
+
key: z.ZodString;
|
|
271
|
+
desc: z.ZodBoolean;
|
|
272
|
+
}, z.core.$strict>>>;
|
|
273
|
+
filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
274
|
+
key: z.ZodString;
|
|
275
|
+
value: z.ZodUnknown;
|
|
276
|
+
}, z.core.$strict>>>;
|
|
277
|
+
page: z.ZodOptional<z.ZodObject<{
|
|
278
|
+
index: z.ZodNumber;
|
|
279
|
+
size: z.ZodNumber;
|
|
280
|
+
}, z.core.$strict>>;
|
|
281
|
+
}, z.core.$strict>;
|
|
282
|
+
export type ServerQuery = z.infer<typeof serverQuerySchema>;
|
|
283
|
+
/**
|
|
284
|
+
* Translates table state into a query for the operations the contract runs on
|
|
285
|
+
* the server. Entries for columns the contract does not define are dropped.
|
|
286
|
+
*/
|
|
287
|
+
export declare function toServerQuery(contract: TableContract, state: QueryState): ServerQuery;
|
|
288
|
+
//#endregion
|
|
289
|
+
//#region src/version.d.ts
|
|
290
|
+
/** Contract schema version written and understood by this SDK. */
|
|
291
|
+
export declare const SCHEMA_VERSION = "1.0";
|
|
292
|
+
/** Minor versions are compatible; a different major version is not. */
|
|
293
|
+
export declare function isSupportedSchemaVersion(version: unknown): boolean;
|
|
294
|
+
/** Upgrades a definition written for an older schema to the current one. */
|
|
295
|
+
export type Migrate = (definition: unknown, fromVersion: unknown) => unknown;
|
|
296
|
+
//#endregion
|
|
297
|
+
//#region src/validate.d.ts
|
|
298
|
+
export interface ValidateOptions {
|
|
299
|
+
/** Upgrades definitions whose schema version this SDK does not support. */
|
|
300
|
+
migrate?: Migrate;
|
|
301
|
+
/** Application-specific checks run after the built-in ones. */
|
|
302
|
+
rules?: ReadonlyArray<ContractRule>;
|
|
303
|
+
}
|
|
304
|
+
/** Validates untrusted JSON and returns a typed contract or diagnostics. */
|
|
305
|
+
export declare function validateContract(input: unknown, { migrate, rules }?: ValidateOptions): Result<TableContract>;
|
|
306
|
+
//#endregion
|
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,305 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
//#region src/ref.ts
|
|
3
|
+
/** A named reference to a function the consuming application registers. */
|
|
4
|
+
const refSchema = z.strictObject({ ref: z.string().min(1) });
|
|
5
|
+
function isRef(value) {
|
|
6
|
+
return refSchema.safeParse(value).success;
|
|
7
|
+
}
|
|
8
|
+
//#endregion
|
|
9
|
+
//#region src/contract.ts
|
|
10
|
+
/** A TanStack built-in function name, or a reference to a registered one. */
|
|
11
|
+
const namedFnSchema = z.union([z.string().min(1), refSchema]);
|
|
12
|
+
/** Literal text, or a reference to a registered renderer. */
|
|
13
|
+
const templateSchema = z.union([z.string(), refSchema]);
|
|
14
|
+
const metaSchema = z.record(z.string(), z.json());
|
|
15
|
+
const executionSchema = z.enum(["client", "server"]);
|
|
16
|
+
const columnSchema = z.strictObject({
|
|
17
|
+
id: z.string().min(1),
|
|
18
|
+
accessorKey: z.string().min(1).optional(),
|
|
19
|
+
accessorFn: refSchema.optional(),
|
|
20
|
+
header: templateSchema.optional(),
|
|
21
|
+
footer: templateSchema.optional(),
|
|
22
|
+
cell: refSchema.optional(),
|
|
23
|
+
/** Formats the cell value when no `cell` renderer is given. */
|
|
24
|
+
formatter: refSchema.optional(),
|
|
25
|
+
/** Row action handlers, exposed to renderers as `meta.actions`. */
|
|
26
|
+
actions: z.array(refSchema).optional(),
|
|
27
|
+
sortFn: namedFnSchema.optional(),
|
|
28
|
+
filterFn: namedFnSchema.optional(),
|
|
29
|
+
aggregationFn: namedFnSchema.optional(),
|
|
30
|
+
enableSorting: z.boolean().optional(),
|
|
31
|
+
enableMultiSort: z.boolean().optional(),
|
|
32
|
+
invertSorting: z.boolean().optional(),
|
|
33
|
+
sortDescFirst: z.boolean().optional(),
|
|
34
|
+
sortUndefined: z.union([
|
|
35
|
+
z.literal(false),
|
|
36
|
+
z.literal(-1),
|
|
37
|
+
z.literal(1),
|
|
38
|
+
z.enum(["first", "last"])
|
|
39
|
+
]).optional(),
|
|
40
|
+
enableColumnFilter: z.boolean().optional(),
|
|
41
|
+
enableGlobalFilter: z.boolean().optional(),
|
|
42
|
+
enableHiding: z.boolean().optional(),
|
|
43
|
+
enableGrouping: z.boolean().optional(),
|
|
44
|
+
enablePinning: z.boolean().optional(),
|
|
45
|
+
enableResizing: z.boolean().optional(),
|
|
46
|
+
size: z.number().nonnegative().optional(),
|
|
47
|
+
minSize: z.number().nonnegative().optional(),
|
|
48
|
+
maxSize: z.number().nonnegative().optional(),
|
|
49
|
+
/** Backend-defined operation identifiers; never raw SQL or field paths. */
|
|
50
|
+
server: z.strictObject({
|
|
51
|
+
sortKey: z.string().min(1).optional(),
|
|
52
|
+
filterKey: z.string().min(1).optional()
|
|
53
|
+
}).optional(),
|
|
54
|
+
meta: metaSchema.optional()
|
|
55
|
+
});
|
|
56
|
+
const defaultsSchema = z.strictObject({
|
|
57
|
+
sorting: z.array(z.strictObject({
|
|
58
|
+
id: z.string(),
|
|
59
|
+
desc: z.boolean()
|
|
60
|
+
})).optional(),
|
|
61
|
+
columnFilters: z.array(z.strictObject({
|
|
62
|
+
id: z.string(),
|
|
63
|
+
value: z.json()
|
|
64
|
+
})).optional(),
|
|
65
|
+
pagination: z.strictObject({
|
|
66
|
+
pageIndex: z.number().int().nonnegative().default(0),
|
|
67
|
+
pageSize: z.number().int().positive()
|
|
68
|
+
}).optional(),
|
|
69
|
+
columnVisibility: z.record(z.string(), z.boolean()).optional()
|
|
70
|
+
});
|
|
71
|
+
const modeSchema = z.strictObject({
|
|
72
|
+
sorting: executionSchema.default("client"),
|
|
73
|
+
filtering: executionSchema.default("client"),
|
|
74
|
+
pagination: executionSchema.default("client")
|
|
75
|
+
});
|
|
76
|
+
const tableContractSchema = z.strictObject({
|
|
77
|
+
schemaVersion: z.string().regex(/^\d+\.\d+$/),
|
|
78
|
+
tableId: z.string().min(1),
|
|
79
|
+
revision: z.number().int().positive(),
|
|
80
|
+
columns: z.array(columnSchema).min(1),
|
|
81
|
+
defaults: defaultsSchema.optional(),
|
|
82
|
+
mode: modeSchema.optional(),
|
|
83
|
+
meta: metaSchema.optional()
|
|
84
|
+
});
|
|
85
|
+
const CLIENT_MODE = modeSchema.parse({});
|
|
86
|
+
/** The contract's execution modes with client-side defaults applied. */
|
|
87
|
+
function getMode(contract) {
|
|
88
|
+
return contract.mode ?? CLIENT_MODE;
|
|
89
|
+
}
|
|
90
|
+
//#endregion
|
|
91
|
+
//#region src/diagnostics.ts
|
|
92
|
+
function hasErrors(diagnostics) {
|
|
93
|
+
return diagnostics.some((diagnostic) => diagnostic.severity === "error");
|
|
94
|
+
}
|
|
95
|
+
/** Converts schema validation issues into error diagnostics under one code. */
|
|
96
|
+
function issuesToDiagnostics(issues, code) {
|
|
97
|
+
return issues.map(({ path, message }) => ({
|
|
98
|
+
code,
|
|
99
|
+
severity: "error",
|
|
100
|
+
path: path.map((key) => typeof key === "symbol" ? String(key) : key),
|
|
101
|
+
message
|
|
102
|
+
}));
|
|
103
|
+
}
|
|
104
|
+
/** A value is only usable when none of its diagnostics are errors. */
|
|
105
|
+
function toResult(value, diagnostics) {
|
|
106
|
+
return hasErrors(diagnostics) ? {
|
|
107
|
+
ok: false,
|
|
108
|
+
diagnostics
|
|
109
|
+
} : {
|
|
110
|
+
ok: true,
|
|
111
|
+
value,
|
|
112
|
+
diagnostics
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
/** Thrown where a failed `Result` cannot be returned to the caller. */
|
|
116
|
+
var ContractError = class extends Error {
|
|
117
|
+
diagnostics;
|
|
118
|
+
constructor(diagnostics) {
|
|
119
|
+
super(diagnostics.map(({ code, path, message }) => `[${code}] ${path.join(".")}: ${message}`).join("\n"));
|
|
120
|
+
this.name = "ContractError";
|
|
121
|
+
this.diagnostics = diagnostics;
|
|
122
|
+
}
|
|
123
|
+
};
|
|
124
|
+
//#endregion
|
|
125
|
+
//#region src/registry.ts
|
|
126
|
+
const REGISTRY_CATEGORIES = [
|
|
127
|
+
"sortFns",
|
|
128
|
+
"filterFns",
|
|
129
|
+
"accessorFns",
|
|
130
|
+
"cells",
|
|
131
|
+
"headers",
|
|
132
|
+
"formatters",
|
|
133
|
+
"actions",
|
|
134
|
+
"aggregationFns"
|
|
135
|
+
];
|
|
136
|
+
var RegistryCollisionError = class extends Error {
|
|
137
|
+
constructor(category, name) {
|
|
138
|
+
super(`"${name}" is registered more than once in ${category}.`);
|
|
139
|
+
this.name = "RegistryCollisionError";
|
|
140
|
+
}
|
|
141
|
+
};
|
|
142
|
+
/** Merges registries contributed by separate application modules. */
|
|
143
|
+
function composeRegistries(registries, { onCollision = "error" } = {}) {
|
|
144
|
+
const composed = Object.fromEntries(REGISTRY_CATEGORIES.map((category) => {
|
|
145
|
+
const entries = {};
|
|
146
|
+
for (const registry of registries) for (const [name, entry] of Object.entries(registry[category] ?? {})) {
|
|
147
|
+
if (onCollision === "error" && Object.hasOwn(entries, name)) throw new RegistryCollisionError(category, name);
|
|
148
|
+
entries[name] = entry;
|
|
149
|
+
}
|
|
150
|
+
return [category, Object.freeze(entries)];
|
|
151
|
+
}));
|
|
152
|
+
return Object.freeze(composed);
|
|
153
|
+
}
|
|
154
|
+
/** Creates a complete, immutable registry from the categories provided. */
|
|
155
|
+
function createRegistry(input = {}) {
|
|
156
|
+
return composeRegistries([input]);
|
|
157
|
+
}
|
|
158
|
+
//#endregion
|
|
159
|
+
//#region src/rules.ts
|
|
160
|
+
const uniqueColumnIds = ({ columns }) => {
|
|
161
|
+
const seen = /* @__PURE__ */ new Set();
|
|
162
|
+
return columns.flatMap(({ id }, index) => {
|
|
163
|
+
if (!seen.has(id)) {
|
|
164
|
+
seen.add(id);
|
|
165
|
+
return [];
|
|
166
|
+
}
|
|
167
|
+
return [{
|
|
168
|
+
code: "duplicate-column-id",
|
|
169
|
+
severity: "error",
|
|
170
|
+
path: [
|
|
171
|
+
"columns",
|
|
172
|
+
index,
|
|
173
|
+
"id"
|
|
174
|
+
],
|
|
175
|
+
message: `Column id "${id}" is used more than once.`
|
|
176
|
+
}];
|
|
177
|
+
});
|
|
178
|
+
};
|
|
179
|
+
const singleAccessor = ({ columns }) => columns.flatMap((column, index) => column.accessorKey !== void 0 && column.accessorFn !== void 0 ? [{
|
|
180
|
+
code: "conflicting-accessors",
|
|
181
|
+
severity: "error",
|
|
182
|
+
path: ["columns", index],
|
|
183
|
+
message: `Column "${column.id}" sets both accessorKey and accessorFn.`
|
|
184
|
+
}] : []);
|
|
185
|
+
const defaultsReferenceColumns = ({ columns, defaults = {} }) => {
|
|
186
|
+
const ids = new Set(columns.map((column) => column.id));
|
|
187
|
+
return [
|
|
188
|
+
...(defaults.sorting ?? []).map(({ id }, index) => [[
|
|
189
|
+
"defaults",
|
|
190
|
+
"sorting",
|
|
191
|
+
index
|
|
192
|
+
], id]),
|
|
193
|
+
...(defaults.columnFilters ?? []).map(({ id }, index) => [[
|
|
194
|
+
"defaults",
|
|
195
|
+
"columnFilters",
|
|
196
|
+
index
|
|
197
|
+
], id]),
|
|
198
|
+
...Object.keys(defaults.columnVisibility ?? {}).map((id) => [[
|
|
199
|
+
"defaults",
|
|
200
|
+
"columnVisibility",
|
|
201
|
+
id
|
|
202
|
+
], id])
|
|
203
|
+
].filter(([, id]) => !ids.has(id)).map(([path, id]) => ({
|
|
204
|
+
code: "unknown-column",
|
|
205
|
+
severity: "error",
|
|
206
|
+
path,
|
|
207
|
+
message: `Defaults reference column "${id}", which is not defined.`
|
|
208
|
+
}));
|
|
209
|
+
};
|
|
210
|
+
/**
|
|
211
|
+
* Sorting, filtering and pagination must run over the same dataset: once the
|
|
212
|
+
* server paginates, the browser only holds one page to sort or filter.
|
|
213
|
+
*/
|
|
214
|
+
const compatibleModes = (contract) => {
|
|
215
|
+
const mode = getMode(contract);
|
|
216
|
+
if (mode.pagination !== "server") return [];
|
|
217
|
+
return ["sorting", "filtering"].filter((operation) => mode[operation] === "client").map((operation) => ({
|
|
218
|
+
code: "mode-mismatch",
|
|
219
|
+
severity: "warning",
|
|
220
|
+
path: ["mode", operation],
|
|
221
|
+
message: `Client-side ${operation} with server-side pagination only applies to the current page.`
|
|
222
|
+
}));
|
|
223
|
+
};
|
|
224
|
+
const contractRules = [
|
|
225
|
+
uniqueColumnIds,
|
|
226
|
+
singleAccessor,
|
|
227
|
+
defaultsReferenceColumns,
|
|
228
|
+
compatibleModes
|
|
229
|
+
];
|
|
230
|
+
//#endregion
|
|
231
|
+
//#region src/server-query.ts
|
|
232
|
+
/** What the data API receives: operation keys instead of column ids. */
|
|
233
|
+
const serverQuerySchema = z.strictObject({
|
|
234
|
+
sort: z.array(z.strictObject({
|
|
235
|
+
key: z.string(),
|
|
236
|
+
desc: z.boolean()
|
|
237
|
+
})).optional(),
|
|
238
|
+
filters: z.array(z.strictObject({
|
|
239
|
+
key: z.string(),
|
|
240
|
+
value: z.unknown()
|
|
241
|
+
})).optional(),
|
|
242
|
+
page: z.strictObject({
|
|
243
|
+
index: z.number().int().nonnegative(),
|
|
244
|
+
size: z.number().int().positive()
|
|
245
|
+
}).optional()
|
|
246
|
+
});
|
|
247
|
+
/**
|
|
248
|
+
* Translates table state into a query for the operations the contract runs on
|
|
249
|
+
* the server. Entries for columns the contract does not define are dropped.
|
|
250
|
+
*/
|
|
251
|
+
function toServerQuery(contract, state) {
|
|
252
|
+
const mode = getMode(contract);
|
|
253
|
+
const columns = new Map(contract.columns.map((column) => [column.id, column]));
|
|
254
|
+
const withKeys = (entries, serverKey) => entries.flatMap(({ id, ...rest }) => {
|
|
255
|
+
const column = columns.get(id);
|
|
256
|
+
return column ? [{
|
|
257
|
+
key: column.server?.[serverKey] ?? id,
|
|
258
|
+
...rest
|
|
259
|
+
}] : [];
|
|
260
|
+
});
|
|
261
|
+
const query = {};
|
|
262
|
+
if (mode.sorting === "server" && state.sorting) query.sort = withKeys(state.sorting, "sortKey");
|
|
263
|
+
if (mode.filtering === "server" && state.columnFilters) query.filters = withKeys(state.columnFilters, "filterKey");
|
|
264
|
+
if (mode.pagination === "server" && state.pagination) query.page = {
|
|
265
|
+
index: state.pagination.pageIndex,
|
|
266
|
+
size: state.pagination.pageSize
|
|
267
|
+
};
|
|
268
|
+
return query;
|
|
269
|
+
}
|
|
270
|
+
//#endregion
|
|
271
|
+
//#region src/version.ts
|
|
272
|
+
/** Contract schema version written and understood by this SDK. */
|
|
273
|
+
const SCHEMA_VERSION = "1.0";
|
|
274
|
+
const major = (version) => version.split(".")[0];
|
|
275
|
+
/** Minor versions are compatible; a different major version is not. */
|
|
276
|
+
function isSupportedSchemaVersion(version) {
|
|
277
|
+
return typeof version === "string" && major(version) === major("1.0");
|
|
278
|
+
}
|
|
279
|
+
//#endregion
|
|
280
|
+
//#region src/validate.ts
|
|
281
|
+
const versionOf = (input) => typeof input === "object" && input !== null && "schemaVersion" in input ? input.schemaVersion : void 0;
|
|
282
|
+
/** Validates untrusted JSON and returns a typed contract or diagnostics. */
|
|
283
|
+
function validateContract(input, { migrate, rules = [] } = {}) {
|
|
284
|
+
let definition = input;
|
|
285
|
+
if (!isSupportedSchemaVersion(versionOf(definition)) && migrate) definition = migrate(definition, versionOf(definition));
|
|
286
|
+
const version = versionOf(definition);
|
|
287
|
+
if (version !== void 0 && !isSupportedSchemaVersion(version)) return {
|
|
288
|
+
ok: false,
|
|
289
|
+
diagnostics: [{
|
|
290
|
+
code: "unsupported-schema-version",
|
|
291
|
+
severity: "error",
|
|
292
|
+
path: ["schemaVersion"],
|
|
293
|
+
message: `Schema version "${String(version)}" is not supported; this SDK supports 1.0.`
|
|
294
|
+
}]
|
|
295
|
+
};
|
|
296
|
+
const parsed = tableContractSchema.safeParse(definition);
|
|
297
|
+
if (!parsed.success) return {
|
|
298
|
+
ok: false,
|
|
299
|
+
diagnostics: issuesToDiagnostics(parsed.error.issues, "invalid-structure")
|
|
300
|
+
};
|
|
301
|
+
const diagnostics = [...contractRules, ...rules].flatMap((rule) => rule(parsed.data));
|
|
302
|
+
return toResult(parsed.data, diagnostics);
|
|
303
|
+
}
|
|
304
|
+
//#endregion
|
|
305
|
+
export { ContractError, REGISTRY_CATEGORIES, RegistryCollisionError, SCHEMA_VERSION, columnSchema, composeRegistries, contractRules, createRegistry, defaultsSchema, getMode, hasErrors, isRef, isSupportedSchemaVersion, issuesToDiagnostics, modeSchema, refSchema, serverQuerySchema, tableContractSchema, toResult, toServerQuery, validateContract };
|
package/package.json
CHANGED
|
@@ -1,6 +1,51 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@colspec/core",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"devDependencies": {
|
|
5
|
+
"@repo/eslint-config": "0.0.0",
|
|
6
|
+
"@repo/typescript-config": "0.0.0"
|
|
7
|
+
},
|
|
8
|
+
"dependencies": {
|
|
9
|
+
"zod": "^4.6.5"
|
|
10
|
+
},
|
|
11
|
+
"type": "module",
|
|
12
|
+
"license": "MIT",
|
|
13
|
+
"files": [
|
|
14
|
+
"dist"
|
|
15
|
+
],
|
|
16
|
+
"publishConfig": {
|
|
17
|
+
"access": "public"
|
|
18
|
+
},
|
|
19
|
+
"sideEffects": false,
|
|
20
|
+
"exports": {
|
|
21
|
+
".": "./dist/index.mjs",
|
|
22
|
+
"./package.json": "./package.json",
|
|
23
|
+
"./contract.schema.json": "./dist/contract.schema.json"
|
|
24
|
+
},
|
|
25
|
+
"description": "JSON contract schema, validation and function registries for dynamic TanStack Table definitions.",
|
|
26
|
+
"author": "Om Prakash Das",
|
|
27
|
+
"homepage": "https://github.com/Om1938/colspec/tree/main/packages/core#readme",
|
|
28
|
+
"bugs": {
|
|
29
|
+
"url": "https://github.com/Om1938/colspec/issues"
|
|
30
|
+
},
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/Om1938/colspec.git",
|
|
34
|
+
"directory": "packages/core"
|
|
35
|
+
},
|
|
36
|
+
"keywords": [
|
|
37
|
+
"tanstack-table",
|
|
38
|
+
"tanstack",
|
|
39
|
+
"table",
|
|
40
|
+
"datagrid",
|
|
41
|
+
"dynamic-columns",
|
|
42
|
+
"colspec",
|
|
43
|
+
"json-schema zod validation"
|
|
44
|
+
],
|
|
45
|
+
"scripts": {
|
|
46
|
+
"lint": "eslint . --max-warnings 0",
|
|
47
|
+
"build": "tsdown && tsx scripts/json-schema.ts",
|
|
48
|
+
"test": "vitest run",
|
|
49
|
+
"check-types": "tsc --noEmit"
|
|
50
|
+
}
|
|
6
51
|
}
|