@dbx-tools/sdk-shared 0.1.20 → 0.1.21
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/README.md +126 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# @dbx-tools/sdk-shared
|
|
2
|
+
|
|
3
|
+
Zod schemas plus inferred TypeScript types for the Databricks SDK
|
|
4
|
+
shapes the rest of the `@dbx-tools/*` packages consume. Everything
|
|
5
|
+
under `./generated/` is regenerated from upstream
|
|
6
|
+
`@databricks/sdk-experimental` `.d.ts` declarations by
|
|
7
|
+
[`scripts/codegen.ts`](../../scripts/codegen.ts); nothing in here is
|
|
8
|
+
hand-maintained.
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import {
|
|
12
|
+
genieMessageSchema,
|
|
13
|
+
genieAttachmentSchema,
|
|
14
|
+
messageStatusSchema,
|
|
15
|
+
type GenieMessage,
|
|
16
|
+
type MessageStatus,
|
|
17
|
+
} from "@dbx-tools/sdk-shared";
|
|
18
|
+
|
|
19
|
+
// Parse / validate a wire payload.
|
|
20
|
+
const message = genieMessageSchema.parse(rawJson);
|
|
21
|
+
|
|
22
|
+
// Or just use the inferred type.
|
|
23
|
+
function format(m: GenieMessage): string {
|
|
24
|
+
return `${m.status}: ${m.content}`;
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The package has zero runtime dependency beyond `zod` itself. No
|
|
29
|
+
`WorkspaceClient`, no `node:*`, no SDK runtime - importing it from a
|
|
30
|
+
browser bundle is safe.
|
|
31
|
+
|
|
32
|
+
## What's inside
|
|
33
|
+
|
|
34
|
+
The single `dashboards` input currently expands to **74 exported
|
|
35
|
+
schemas + matching inferred types**, covering the Genie and Lakeview
|
|
36
|
+
SDK surfaces (conversations, messages, attachments, query results,
|
|
37
|
+
suggested questions, dashboard schedules, subscriptions, etc.). The
|
|
38
|
+
full list lives at
|
|
39
|
+
[`./generated/dashboards.zod.ts`](./generated/dashboards.zod.ts) and
|
|
40
|
+
the package barrel at
|
|
41
|
+
[`./generated/index.ts`](./generated/index.ts).
|
|
42
|
+
|
|
43
|
+
For each upstream type the generator emits two exports:
|
|
44
|
+
|
|
45
|
+
| Export | Shape |
|
|
46
|
+
| ------------------ | ------------------------------------------- |
|
|
47
|
+
| `xxxSchema` | `z.ZodType<X>` for runtime validation |
|
|
48
|
+
| `XxxType` (alias) | `z.infer<typeof xxxSchema>` for static use |
|
|
49
|
+
|
|
50
|
+
## How codegen works
|
|
51
|
+
|
|
52
|
+
Each consumer package declares its own `codegen.inputs` in
|
|
53
|
+
`package.json`:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"name": "@dbx-tools/sdk-shared",
|
|
58
|
+
"codegen": {
|
|
59
|
+
"inputs": [
|
|
60
|
+
"node_modules/@databricks/sdk-experimental/dist/apis/dashboards/model.d.ts"
|
|
61
|
+
]
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`bun scripts/codegen.ts` walks every package with a `codegen` field
|
|
67
|
+
and, for each input:
|
|
68
|
+
|
|
69
|
+
1. Reads the upstream `.d.ts`.
|
|
70
|
+
2. Strips every `import` declaration and rewrites any type reference
|
|
71
|
+
whose root identifier was introduced by one of those imports
|
|
72
|
+
(`sql.StatementResponse`, `ApiClient`, ...) to `unknown`. The
|
|
73
|
+
output is a pure data-shape surface; peer SDK runtime modules
|
|
74
|
+
don't belong here.
|
|
75
|
+
3. Pipes the cleaned source into [`ts-to-zod`](https://github.com/fabien0102/ts-to-zod)
|
|
76
|
+
to produce a `<name>.zod.ts` schema module.
|
|
77
|
+
4. Regenerates `generated/index.ts` as a barrel re-export of every
|
|
78
|
+
schema module.
|
|
79
|
+
|
|
80
|
+
The whole `generated/` tree is gitignored (`generated/.gitignore`
|
|
81
|
+
holds `*`); the hand-tracked top-level `./index.ts` re-exports it so
|
|
82
|
+
the publish merge in [`scripts/release.ts`](../../scripts/release.ts)
|
|
83
|
+
picks up the standard `package.default.json` `exports` map without
|
|
84
|
+
any per-package wiring.
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
// index.ts
|
|
88
|
+
export * from "./generated/index.js";
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Regenerating
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
bun run prebuild # runs codegen across every package with a codegen field
|
|
95
|
+
# or, just sdk-shared:
|
|
96
|
+
bun scripts/codegen.ts
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Codegen refuses to write or delete any file inside `generated/` that
|
|
100
|
+
isn't already gitignored at the start of the run, so manually
|
|
101
|
+
dropping a file into `generated/` without updating the ignore aborts
|
|
102
|
+
with a clear error instead of silently overwriting.
|
|
103
|
+
|
|
104
|
+
## Adding a new SDK surface
|
|
105
|
+
|
|
106
|
+
Append the upstream `.d.ts` path to `codegen.inputs` and rerun
|
|
107
|
+
codegen. Optionally append `=<basename>` to override the auto-derived
|
|
108
|
+
file name:
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"codegen": {
|
|
113
|
+
"inputs": [
|
|
114
|
+
"node_modules/@databricks/sdk-experimental/dist/apis/dashboards/model.d.ts",
|
|
115
|
+
"node_modules/@databricks/sdk-experimental/dist/apis/jobs/model.d.ts=jobs"
|
|
116
|
+
]
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
That produces `generated/dashboards.zod.ts` and `generated/jobs.zod.ts`,
|
|
122
|
+
both re-exported by `generated/index.ts`.
|
|
123
|
+
|
|
124
|
+
## License
|
|
125
|
+
|
|
126
|
+
Apache-2.0
|