Debian Codegraph @

lualib/lua_shape/MIGRATION.md

raw
1 # Migration Guide: tableshape to lua_shape
2
3 This guide helps migrate from tableshape to the new lua_shape library.
4
5 ## Basic Concepts
6
7 ### Module Import
8
9 **tableshape:**
10 ```lua
11 local ts = require("tableshape").types
12 ```
13
14 **lua_shape:**
15 ```lua
16 local T = require "lua_shape.core"
17
18 -- Only need Registry if using schema registration/refs:
19 local Registry = require "lua_shape.registry" -- optional
20 ```
21
22 Note: All utility functions (like `format_error`) are included in the core module, so you only need one require statement for most use cases.
23
24 ## Type Constructors
25
26 ### Scalar Types
27
28 | tableshape | rspamd_schema | Notes |
29 |------------|---------------|-------|
30 | `ts.string` | `T.string()` | |
31 | `ts.number` | `T.number()` | |
32 | `ts.integer` | `T.integer()` | |
33 | `ts.boolean` | `T.boolean()` | |
34 | `ts.literal("foo")` | `T.literal("foo")` | |
35 | `ts.one_of{"a","b"}` | `T.enum({"a","b"})` | For simple value enums |
36
37 ### Constraints
38
39 **tableshape:**
40 ```lua
41 ts.string:length(3, 10) -- min 3, max 10
42 ts.number:range(0, 100)
43 ```
44
45 **rspamd_schema:**
46 ```lua
47 T.string({ min_len = 3, max_len = 10 })
48 T.number({ min = 0, max = 100 })
49 T.integer({ min = 0, max = 100 })
50 ```
51
52 ### Arrays
53
54 **tableshape:**
55 ```lua
56 ts.array_of(ts.string)
57 ```
58
59 **rspamd_schema:**
60 ```lua
61 T.array(T.string())
62 ```
63
64 ### Tables (Shapes)
65
66 **tableshape:**
67 ```lua
68 ts.shape({
69 name = ts.string,
70 age = ts.number,
71 email = ts.string:is_optional()
72 })
73 ```
74
75 **rspamd_schema:**
76 ```lua
77 T.table({
78 name = T.string(),
79 age = T.number(),
80 email = { schema = T.string(), optional = true }
81 })
82
83 -- Or using :optional() method:
84 T.table({
85 name = T.string(),
86 age = T.number(),
87 email = T.string():optional()
88 })
89 ```
90
91 ### Optional Fields
92
93 **tableshape:**
94 ```lua
95 field = ts.string:is_optional()
96 ```
97
98 **rspamd_schema:**
99 ```lua
100 -- Method 1: inline
101 field = { schema = T.string(), optional = true }
102
103 -- Method 2: using :optional()
104 field = T.string():optional()
105 ```
106
107 ### Default Values
108
109 **tableshape:**
110 ```lua
111 field = ts.string:is_optional() -- then handle defaults manually
112 ```
113
114 **rspamd_schema:**
115 ```lua
116 field = { schema = T.string(), optional = true, default = "default_value" }
117
118 -- Or using :with_default()
119 field = T.string():with_default("default_value")
120 ```
121
122 ## Operators
123
124 ### Union (one_of)
125
126 **tableshape:**
127 ```lua
128 ts.string + ts.number
129 ```
130
131 **rspamd_schema:**
132 ```lua
133 T.one_of({ T.string(), T.number() })
134 ```
135
136 ### Transform
137
138 **tableshape:**
139 ```lua
140 ts.string / tonumber
141 ts.string / function(v) return v:upper() end
142 ```
143
144 **rspamd_schema:**
145 ```lua
146 T.string():transform_with(tonumber)
147 T.string():transform_with(function(v) return v:upper() end)
148
149 -- Or using T.transform:
150 T.transform(T.string(), tonumber)
151 ```
152
153 ### Chained Transforms
154
155 **tableshape:**
156 ```lua
157 (ts.string / tonumber) * ts.number
158 ```
159
160 **rspamd_schema:**
161 ```lua
162 T.string():transform_with(tonumber):transform_with(function(v)
163 return T.number():check(v) and v or error("not a number")
164 end)
165
166 -- Better: validate after transform
167 T.transform(T.number(), function(v)
168 return tonumber(v) or 0
169 end)
170 ```
171
172 ## one_of with Multiple Shapes
173
174 **tableshape:**
175 ```lua
176 ts.one_of {
177 ts.shape({ type = ts.literal("file"), path = ts.string }),
178 ts.shape({ type = ts.literal("redis"), host = ts.string }),
179 }
180 ```
181
182 **rspamd_schema:**
183 ```lua
184 T.one_of({
185 {
186 name = "file_config",
187 schema = T.table({
188 type = T.literal("file"),
189 path = T.string()
190 })
191 },
192 {
193 name = "redis_config",
194 schema = T.table({
195 type = T.literal("redis"),
196 host = T.string()
197 })
198 }
199 })
200 ```
201
202 ## Documentation
203
204 **tableshape:**
205 ```lua
206 ts.string:describe("User name")
207 ```
208
209 **rspamd_schema:**
210 ```lua
211 T.string():doc({
212 summary = "User name",
213 description = "Full description here",
214 examples = {"alice", "bob"}
215 })
216 ```
217
218 ## Complex Example: Redis Options
219
220 **tableshape:**
221 ```lua
222 local ts = require("tableshape").types
223
224 local db_schema = (ts.number / tostring + ts.string):is_optional()
225
226 local common_schema = {
227 timeout = (ts.number + ts.string / parse_time):is_optional(),
228 db = db_schema,
229 password = ts.string:is_optional(),
230 }
231
232 local servers_schema = table_merge({
233 servers = ts.string + ts.array_of(ts.string),
234 }, common_schema)
235
236 local redis_schema = ts.one_of {
237 ts.shape(common_schema),
238 ts.shape(servers_schema),
239 }
240 ```
241
242 **lua_shape:**
243 ```lua
244 local T = require "lua_shape.core"
245
246 -- Accept string or number for db
247 local db_schema = T.one_of({
248 T.number(),
249 T.string()
250 }):optional():doc({ summary = "Database number" })
251
252 -- Accept number or time string for timeout
253 local timeout_schema = T.transform(T.number({ min = 0 }), function(val)
254 if type(val) == "number" then return val end
255 if type(val) == "string" then return parse_time(val) end
256 error("Expected number or time string")
257 end):optional():doc({ summary = "Connection timeout" })
258
259 -- Common fields
260 local common_fields = {
261 timeout = timeout_schema,
262 db = db_schema,
263 password = T.string():optional()
264 }
265
266 -- Servers field accepts string or array
267 local servers_field = T.one_of({
268 T.string(),
269 T.array(T.string())
270 })
271
272 -- Define variants
273 local redis_schema = T.one_of({
274 {
275 name = "no_servers",
276 schema = T.table(common_fields)
277 },
278 {
279 name = "with_servers",
280 schema = T.table(table_merge({
281 servers = servers_field
282 }, common_fields))
283 }
284 })
285 ```
286
287 Key improvements:
288 - Better error messages with intersection ("all alternatives require: db, timeout")
289 - Named variants for clarity
290 - Transform semantics explicit
291 - Documentation embedded in schema
292
293 ## Validation
294
295 ### Check Mode
296
297 **tableshape:**
298 ```lua
299 local ok, err = schema:transform(config)
300 if not ok then
301 logger.errx("Invalid config: %s", err)
302 end
303 ```
304
305 **lua_shape:**
306 ```lua
307 local T = require "lua_shape.core"
308
309 local ok, val_or_err = schema:check(config)
310 if not ok then
311 logger.errx("Invalid config:\n%s", T.format_error(val_or_err))
312 end
313 ```
314
315 ### Transform Mode
316
317 **tableshape:**
318 ```lua
319 local ok, result = schema:transform(config)
320 ```
321
322 **rspamd_schema:**
323 ```lua
324 local ok, result = schema:transform(config)
325 -- result will have defaults applied and transforms executed
326 ```
327
328 ## Key Differences
329
330 1. **Explicit vs Operator-based:**
331 - tableshape uses operators (`+`, `/`, `*`) for composition
332 - rspamd_schema uses explicit methods and constructors
333
334 2. **Error Reporting:**
335 - tableshape returns string errors
336 - rspamd_schema returns structured error trees with better messages
337
338 3. **one_of Intersection:**
339 - rspamd_schema computes intersection of table variants for better error messages
340 - Shows "all alternatives require field X" instead of listing every variant error
341
342 4. **Mixins:**
343 - rspamd_schema has first-class mixin support with origin tracking
344 - Can show "field from mixin redis" in docs and errors
345
346 5. **Export:**
347 - rspamd_schema can export to JSON Schema
348 - Can generate documentation IR from schemas
349
350 ## Migration Strategy
351
352 1. Start with standalone schemas (not referenced by other code yet)
353 2. Test validation and error messages
354 3. Gradually replace tableshape imports
355 4. Update schema definitions
356 5. Update validation call sites
357 6. Remove tableshape dependency when complete
358
359 ## Helper Patterns
360
361 ### Common Transform Pattern
362
363 For fields that accept multiple types with normalization:
364
365 **tableshape:**
366 ```lua
367 (ts.string + ts.number) / normalize_fn
368 ```
369
370 **rspamd_schema:**
371 ```lua
372 T.one_of({
373 T.string():transform_with(normalize_fn),
374 T.number():transform_with(normalize_fn)
375 })
376
377 -- Or apply transform after one_of:
378 T.one_of({ T.string(), T.number() }):transform_with(normalize_fn)
379 ```
380
381 ### Optional with Transform
382
383 **tableshape:**
384 ```lua
385 (ts.string / tonumber):is_optional()
386 ```
387
388 **rspamd_schema:**
389 ```lua
390 T.string():transform_with(tonumber):optional()
391
392 -- Or with default:
393 T.string():transform_with(tonumber):with_default(0)
394 ```