@acryldev/create-blends 0.0.0-stage → 1.7.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 (103) hide show
  1. package/README.md +104 -2
  2. package/bin/create-acrylblends.js +12 -0
  3. package/dist/index.d.ts +94 -0
  4. package/dist/index.js +1069 -0
  5. package/dist/index.js.map +1 -0
  6. package/docs/framework/LICENSE +23 -0
  7. package/docs/framework/README.md +70 -0
  8. package/docs/framework/agents/index.md +59 -0
  9. package/docs/framework/api/acryl.md +247 -0
  10. package/docs/framework/api/context.md +478 -0
  11. package/docs/framework/api/exception.md +80 -0
  12. package/docs/framework/api/index.md +12 -0
  13. package/docs/framework/api/presets.md +62 -0
  14. package/docs/framework/api/request.md +396 -0
  15. package/docs/framework/api/routing.md +303 -0
  16. package/docs/framework/api/summary.md +143 -0
  17. package/docs/framework/concepts/benchmarks.md +26 -0
  18. package/docs/framework/concepts/developer-experience.md +5 -0
  19. package/docs/framework/concepts/middleware.md +21 -0
  20. package/docs/framework/concepts/motivation.md +14 -0
  21. package/docs/framework/concepts/routers.md +63 -0
  22. package/docs/framework/concepts/stacks.md +235 -0
  23. package/docs/framework/concepts/web-standard.md +27 -0
  24. package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
  25. package/docs/framework/cordis/concepts.md +105 -0
  26. package/docs/framework/cordis/middleware.md +8 -0
  27. package/docs/framework/cordis/migration-from-0-3.md +111 -0
  28. package/docs/framework/cordis/migration-from-0-4.md +14 -0
  29. package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
  30. package/docs/framework/cordis/migration-to-1-0.md +46 -0
  31. package/docs/framework/cordis/mounting.md +85 -0
  32. package/docs/framework/cordis/node-server.md +100 -0
  33. package/docs/framework/cordis/plugin-lifecycle.md +111 -0
  34. package/docs/framework/cordis/surfaces.md +71 -0
  35. package/docs/framework/cordis/transport-and-cancellation.md +57 -0
  36. package/docs/framework/cordis/validation.md +135 -0
  37. package/docs/framework/getting-started/basic.md +201 -0
  38. package/docs/framework/getting-started/bun.md +219 -0
  39. package/docs/framework/getting-started/deploy.md +133 -0
  40. package/docs/framework/getting-started/desktop.md +80 -0
  41. package/docs/framework/getting-started/nodejs.md +365 -0
  42. package/docs/framework/getting-started/other-runtimes.md +30 -0
  43. package/docs/framework/guides/best-practices.md +231 -0
  44. package/docs/framework/guides/bring-your-own-tool.md +218 -0
  45. package/docs/framework/guides/client-modules.md +210 -0
  46. package/docs/framework/guides/create-acrylblends.md +143 -0
  47. package/docs/framework/guides/data.md +314 -0
  48. package/docs/framework/guides/examples.md +3 -0
  49. package/docs/framework/guides/faq.md +19 -0
  50. package/docs/framework/guides/forms-and-sessions.md +235 -0
  51. package/docs/framework/guides/helpers.md +33 -0
  52. package/docs/framework/guides/jsx-dom.md +301 -0
  53. package/docs/framework/guides/jsx.md +487 -0
  54. package/docs/framework/guides/middleware.md +253 -0
  55. package/docs/framework/guides/production.md +80 -0
  56. package/docs/framework/guides/rpc.md +878 -0
  57. package/docs/framework/guides/testing.md +133 -0
  58. package/docs/framework/guides/validation.md +470 -0
  59. package/docs/framework/helpers/accepts.md +60 -0
  60. package/docs/framework/helpers/adapter.md +57 -0
  61. package/docs/framework/helpers/conninfo.md +77 -0
  62. package/docs/framework/helpers/cookie.md +232 -0
  63. package/docs/framework/helpers/css.md +282 -0
  64. package/docs/framework/helpers/dev.md +64 -0
  65. package/docs/framework/helpers/factory.md +180 -0
  66. package/docs/framework/helpers/html.md +123 -0
  67. package/docs/framework/helpers/jwt.md +184 -0
  68. package/docs/framework/helpers/proxy.md +115 -0
  69. package/docs/framework/helpers/route.md +143 -0
  70. package/docs/framework/helpers/ssg.md +390 -0
  71. package/docs/framework/helpers/streaming.md +224 -0
  72. package/docs/framework/helpers/testing.md +118 -0
  73. package/docs/framework/helpers/websocket.md +208 -0
  74. package/docs/framework/middleware/builtin/basic-auth.md +165 -0
  75. package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
  76. package/docs/framework/middleware/builtin/body-limit.md +71 -0
  77. package/docs/framework/middleware/builtin/cache.md +99 -0
  78. package/docs/framework/middleware/builtin/combine.md +94 -0
  79. package/docs/framework/middleware/builtin/compress.md +59 -0
  80. package/docs/framework/middleware/builtin/context-storage.md +74 -0
  81. package/docs/framework/middleware/builtin/cors.md +134 -0
  82. package/docs/framework/middleware/builtin/csrf.md +105 -0
  83. package/docs/framework/middleware/builtin/etag.md +54 -0
  84. package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
  85. package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
  86. package/docs/framework/middleware/builtin/jwk.md +192 -0
  87. package/docs/framework/middleware/builtin/jwt.md +145 -0
  88. package/docs/framework/middleware/builtin/language.md +232 -0
  89. package/docs/framework/middleware/builtin/logger.md +74 -0
  90. package/docs/framework/middleware/builtin/loopback-only.md +31 -0
  91. package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
  92. package/docs/framework/middleware/builtin/method-override.md +80 -0
  93. package/docs/framework/middleware/builtin/mount.md +103 -0
  94. package/docs/framework/middleware/builtin/pretty-json.md +53 -0
  95. package/docs/framework/middleware/builtin/request-id.md +87 -0
  96. package/docs/framework/middleware/builtin/secure-headers.md +247 -0
  97. package/docs/framework/middleware/builtin/timeout.md +98 -0
  98. package/docs/framework/middleware/builtin/timing.md +100 -0
  99. package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
  100. package/docs/framework/middleware/third-party.md +4 -0
  101. package/docs/framework/workshop/README.md +294 -0
  102. package/docs/framework/workshop/facilitator.md +101 -0
  103. package/package.json +54 -3
@@ -0,0 +1,133 @@
1
+ # Testing
2
+
3
+ [Vitest]: https://vitest.dev/
4
+
5
+ Testing is important.
6
+ In actuality, it is easy to test Acryl's applications.
7
+ The way to create a test environment differs from each runtime, but the basic steps are the same.
8
+ In this section, let's test with [Vitest] on Node.js. The same tests run on Bun with its own test runner, because an app is a function from `Request` to `Response`.
9
+
10
+ ## Request and Response
11
+
12
+ All you need to do is create a Request and pass it to the Acryl application to validate the Response. You can then use the useful `app.request` method.
13
+
14
+ > **Tip.** For a typed test client see the [testing helper](../helpers/testing.md).
15
+
16
+ For example, consider an application that provides the following REST API.
17
+
18
+ ```ts
19
+ app.get('/posts', (c) => {
20
+ return c.text('Many posts')
21
+ })
22
+
23
+ app.post('/posts', (c) => {
24
+ return c.json(
25
+ {
26
+ message: 'Created',
27
+ },
28
+ 201,
29
+ {
30
+ 'X-Custom': 'Thank you',
31
+ }
32
+ )
33
+ })
34
+ ```
35
+
36
+ Make a request to `GET /posts` and test the response.
37
+
38
+ ```ts
39
+ describe('Example', () => {
40
+ test('GET /posts', async () => {
41
+ const res = await app.request('/posts')
42
+ expect(res.status).toBe(200)
43
+ expect(await res.text()).toBe('Many posts')
44
+ })
45
+ })
46
+ ```
47
+
48
+ To make a request to `POST /posts`, do the following.
49
+
50
+ ```ts
51
+ test('POST /posts', async () => {
52
+ const res = await app.request('/posts', {
53
+ method: 'POST',
54
+ })
55
+ expect(res.status).toBe(201)
56
+ expect(res.headers.get('X-Custom')).toBe('Thank you')
57
+ expect(await res.json()).toEqual({
58
+ message: 'Created',
59
+ })
60
+ })
61
+ ```
62
+
63
+ To make a request to `POST /posts` with `JSON` data, do the following.
64
+
65
+ ```ts
66
+ test('POST /posts', async () => {
67
+ const res = await app.request('/posts', {
68
+ method: 'POST',
69
+ body: JSON.stringify({ message: 'hello acrylblends' }),
70
+ headers: new Headers({ 'Content-Type': 'application/json' }),
71
+ })
72
+ expect(res.status).toBe(201)
73
+ expect(res.headers.get('X-Custom')).toBe('Thank you')
74
+ expect(await res.json()).toEqual({
75
+ message: 'Created',
76
+ })
77
+ })
78
+ ```
79
+
80
+ To make a request to `POST /posts` with `multipart/form-data` data, do the following.
81
+
82
+ ```ts
83
+ test('POST /posts', async () => {
84
+ const formData = new FormData()
85
+ formData.append('message', 'hello')
86
+ const res = await app.request('/posts', {
87
+ method: 'POST',
88
+ body: formData,
89
+ })
90
+ expect(res.status).toBe(201)
91
+ expect(res.headers.get('X-Custom')).toBe('Thank you')
92
+ expect(await res.json()).toEqual({
93
+ message: 'Created',
94
+ })
95
+ })
96
+ ```
97
+
98
+ You can also pass an instance of the Request class.
99
+
100
+ ```ts
101
+ test('POST /posts', async () => {
102
+ const req = new Request('http://localhost/posts', {
103
+ method: 'POST',
104
+ })
105
+ const res = await app.request(req)
106
+ expect(res.status).toBe(201)
107
+ expect(res.headers.get('X-Custom')).toBe('Thank you')
108
+ expect(await res.json()).toEqual({
109
+ message: 'Created',
110
+ })
111
+ })
112
+ ```
113
+
114
+ In this way, you can test it as like an End-to-End.
115
+
116
+ ## Env
117
+
118
+ To set `c.env` for testing, you can pass it as the 3rd parameter to `app.request`. This is useful for mocking values like platform bindings:
119
+
120
+ ```ts
121
+ const MOCK_ENV = {
122
+ API_HOST: 'example.com',
123
+ DB: {
124
+ prepare: () => {
125
+ /* mocked D1 */
126
+ },
127
+ },
128
+ }
129
+
130
+ test('GET /posts', async () => {
131
+ const res = await app.request('/posts', {}, MOCK_ENV)
132
+ })
133
+ ```
@@ -0,0 +1,470 @@
1
+ # Validation
2
+
3
+ Acryl provides only a very thin Validator.
4
+ However, it can be powerful when combined with a third-party Validator.
5
+ In addition, the RPC feature allows you to share API specifications with your clients through types.
6
+
7
+ ## Manual validator
8
+
9
+ First, introduce a way to validate incoming values without using the third-party Validator.
10
+
11
+ Import `validator` from `acrylblends/validator`.
12
+
13
+ ```ts
14
+ import { validator } from '@acryldev/blends/validator'
15
+ ```
16
+
17
+ To validate form data, specify `form` as the first argument and a callback as the second argument.
18
+ In the callback, validates the value and return the validated values at the end.
19
+ The `validator` can be used as middleware.
20
+
21
+ ```ts
22
+ app.post(
23
+ '/posts',
24
+ validator('form', (value, c) => {
25
+ const body = value['body']
26
+ if (!body || typeof body !== 'string') {
27
+ return c.text('Invalid!', 400)
28
+ }
29
+ return {
30
+ body: body,
31
+ }
32
+ }),
33
+ //...
34
+ ```
35
+
36
+ Within the handler, you can get the validated value with `c.req.valid('form')`.
37
+
38
+ ```ts
39
+ , (c) => {
40
+ const { body } = c.req.valid('form')
41
+ // ... do something
42
+ return c.json(
43
+ {
44
+ message: 'Created!',
45
+ },
46
+ 201
47
+ )
48
+ }
49
+ ```
50
+
51
+ Validation targets include `json`, `query`, `header`, `param` and `cookie` in addition to `form`.
52
+
53
+ **Warning.**
54
+
55
+ When you validate `json` or `form`, the request _must_ contain a matching `content-type` header (e.g. `Content-Type: application/json` for `json`). Otherwise, the request body will not be parsed and you will receive an empty object (`{}`) as value in the callback.
56
+
57
+ It is important to set the `content-type` header when testing using
58
+ [`app.request()`](../api/request.md).
59
+
60
+ Given an application like this.
61
+
62
+ ```ts
63
+ const app = new Acryl()
64
+ app.post(
65
+ '/testing',
66
+ validator('json', (value, c) => {
67
+ // pass-through validator
68
+ return value
69
+ }),
70
+ (c) => {
71
+ const body = c.req.valid('json')
72
+ return c.json(body)
73
+ }
74
+ )
75
+ ```
76
+
77
+ Your tests can be written like this.
78
+
79
+ ```ts
80
+ // ❌ this will not work
81
+ const res = await app.request('/testing', {
82
+ method: 'POST',
83
+ body: JSON.stringify({ key: 'value' }),
84
+ })
85
+ const data = await res.json()
86
+ console.log(data) // {}
87
+
88
+ // ✅ this will work
89
+ const res = await app.request('/testing', {
90
+ method: 'POST',
91
+ body: JSON.stringify({ key: 'value' }),
92
+ headers: new Headers({ 'Content-Type': 'application/json' }),
93
+ })
94
+ const data = await res.json()
95
+ console.log(data) // { key: 'value' }
96
+ ```
97
+
98
+ **Warning.**
99
+
100
+ When you validate `header`, you need to use **lowercase** name as the key.
101
+
102
+ If you want to validate the `Idempotency-Key` header, you need to use `idempotency-key` as the key.
103
+
104
+ ```ts
105
+ // ❌ this will not work
106
+ app.post(
107
+ '/api',
108
+ validator('header', (value, c) => {
109
+ // idempotencyKey is always undefined
110
+ // so this middleware always return 400 as not expected
111
+ const idempotencyKey = value['Idempotency-Key']
112
+
113
+ if (idempotencyKey == undefined || idempotencyKey === '') {
114
+ throw new HTTPException(400, {
115
+ message: 'Idempotency-Key is required',
116
+ })
117
+ }
118
+ return { idempotencyKey }
119
+ }),
120
+ (c) => {
121
+ const { idempotencyKey } = c.req.valid('header')
122
+ // ...
123
+ }
124
+ )
125
+
126
+ // ✅ this will work
127
+ app.post(
128
+ '/api',
129
+ validator('header', (value, c) => {
130
+ // can retrieve the value of the header as expected
131
+ const idempotencyKey = value['idempotency-key']
132
+
133
+ if (idempotencyKey == undefined || idempotencyKey === '') {
134
+ throw new HTTPException(400, {
135
+ message: 'Idempotency-Key is required',
136
+ })
137
+ }
138
+ return { idempotencyKey }
139
+ }),
140
+ (c) => {
141
+ const { idempotencyKey } = c.req.valid('header')
142
+ // ...
143
+ }
144
+ )
145
+ ```
146
+
147
+ ## Validating an HTML form
148
+
149
+ A browser posts a `<form>` as `application/x-www-form-urlencoded`, or as `multipart/form-data` when it has `enctype="multipart/form-data"` (needed
150
+ for file inputs). `validator('form', ...)` parses both. Each field arrives as a `string`, a file input as a `File`, and a name that appears more
151
+ than once (several checkboxes, or a name ending in `[]`) as an array, so the value has the type `Record<string, string | File | (string | File)[]>`.
152
+
153
+ This page shows a form and re-renders it with a message when a field is wrong:
154
+
155
+ ```ts
156
+ import { Acryl } from '@acryldev/blends'
157
+ import { html } from '@acryldev/blends/html'
158
+ import { validator } from '@acryldev/blends/validator'
159
+
160
+ const page = (error?: string) => html`<!doctype html>
161
+ <form method="post" action="/notes" enctype="multipart/form-data">
162
+ <input name="title" required>
163
+ <textarea name="body"></textarea>
164
+ <input type="file" name="attachment">
165
+ <button>Save</button>
166
+ ${error === undefined ? '' : html`<p role="alert">${error}</p>`}
167
+ </form>`
168
+
169
+ const app = new Acryl()
170
+ .get('/notes/new', (c) => c.html(page()))
171
+ .post(
172
+ '/notes',
173
+ validator('form', (form, c) => {
174
+ const { title, body, attachment } = form
175
+ if (typeof title !== 'string' || title.trim() === '') return c.html(page('Title is required'), 400)
176
+ if (body !== undefined && typeof body !== 'string') return c.html(page('Body must be text'), 400)
177
+ if (attachment !== undefined && !(attachment instanceof File)) return c.html(page('Attachment must be one file'), 400)
178
+ return {
179
+ title: title.trim(),
180
+ body: body ?? '',
181
+ // A file input left empty still sends a part: a File with no name and no bytes.
182
+ attachment: attachment !== undefined && attachment.size > 0 ? attachment : undefined,
183
+ }
184
+ }),
185
+ (c) => {
186
+ const { title, attachment } = c.req.valid('form') // { title: string, body: string, attachment: File | undefined }
187
+ return c.text(`Saved ${title}${attachment === undefined ? '' : ` with ${attachment.name}`}`, 201)
188
+ }
189
+ )
190
+ ```
191
+
192
+ The messages are escaped by `html`, so a field value shown back in the page cannot inject markup.
193
+
194
+ ### With a schema
195
+
196
+ `schemaValidator('form', schema)` takes the same value. It answers a failure with 400 and JSON issues, which suits a form your own script submits
197
+ with `fetch()`:
198
+
199
+ ```ts
200
+ import * as z from 'zod'
201
+ import { schemaValidator } from '@acryldev/blends/schema-validator'
202
+
203
+ const NoteForm = z.object({
204
+ title: z.string().trim().min(1, 'Title is required'),
205
+ body: z.string().default(''),
206
+ attachment: z.instanceof(File).optional(),
207
+ })
208
+
209
+ app.post('/api/notes', schemaValidator('form', NoteForm), (c) => {
210
+ const { title } = c.req.valid('form') // typed by the schema's output
211
+ return c.json({ title }, 201)
212
+ })
213
+ ```
214
+
215
+ For a plain HTML form, call the schema inside `validator('form', ...)` to re-render the page with the first message instead:
216
+
217
+ ```ts
218
+ validator('form', (form, c) => {
219
+ const result = NoteForm.safeParse(form)
220
+ return result.success ? result.data : c.html(page(result.error.issues[0]?.message), 400)
221
+ })
222
+ ```
223
+
224
+ To test a form route, send a `FormData`: `app.request` sets the `multipart/form-data` content type with its boundary itself.
225
+
226
+ ```ts
227
+ const form = new FormData()
228
+ form.set('title', 'Groceries')
229
+ form.set('attachment', new File(['milk'], 'list.txt', { type: 'text/plain' }))
230
+ const res = await app.request('/notes', { method: 'POST', body: form })
231
+ // res.status === 201, await res.text() === 'Saved Groceries with list.txt'
232
+ ```
233
+
234
+ ## Multiple validators
235
+
236
+ You can also include multiple validators to validate different parts of request:
237
+
238
+ ```ts
239
+ app.post(
240
+ '/posts/:id',
241
+ validator('param', ...),
242
+ validator('query', ...),
243
+ validator('json', ...),
244
+ (c) => {
245
+ //...
246
+ }
247
+ )
248
+ ```
249
+
250
+ ## With Zod
251
+
252
+ You can use [Zod](https://zod.dev), one of third-party validators.
253
+ We recommend using a third-party validator.
254
+
255
+ Install from the Npm registry.
256
+
257
+ **npm**
258
+
259
+ ```sh
260
+ npm i zod
261
+ ```
262
+
263
+ **yarn**
264
+
265
+ ```sh
266
+ yarn add zod
267
+ ```
268
+
269
+ **pnpm**
270
+
271
+ ```sh
272
+ pnpm add zod
273
+ ```
274
+
275
+ **bun**
276
+
277
+ ```sh
278
+ bun add zod
279
+ ```
280
+
281
+ Import `z` from `zod`.
282
+
283
+ ```ts
284
+ import * as z from 'zod'
285
+ ```
286
+
287
+ Write your schema.
288
+
289
+ ```ts
290
+ const schema = z.object({
291
+ body: z.string(),
292
+ })
293
+ ```
294
+
295
+ You can use the schema in the callback function for validation and return the validated value.
296
+
297
+ ```ts
298
+ const route = app.post(
299
+ '/posts',
300
+ validator('form', (value, c) => {
301
+ const parsed = schema.safeParse(value)
302
+ if (!parsed.success) {
303
+ return c.text('Invalid!', 400)
304
+ }
305
+ return parsed.data
306
+ }),
307
+ (c) => {
308
+ const { body } = c.req.valid('form')
309
+ // ... do something
310
+ return c.json(
311
+ {
312
+ message: 'Created!',
313
+ },
314
+ 201
315
+ )
316
+ }
317
+ )
318
+ ```
319
+
320
+ ## Standard Schema validator
321
+
322
+ [Standard Schema](https://standardschema.dev/) is a specification that gives TypeScript validation libraries a common interface, so a tool can accept Zod, Valibot, ArkType and
323
+ others without an adapter for each.
324
+
325
+ `schemaValidator` is part of acrylblends: it validates a request target with any Standard Schema and makes the parsed value available as `c.req.valid(target)`.
326
+
327
+ ```ts
328
+ import { schemaValidator } from '@acryldev/blends/schema-validator'
329
+ ```
330
+
331
+ A failed validation answers 400 with `{ "error": "invalid <target>", "issues": [{ "message", "path" }] }`. The failure shapes, the JSON `Content-Type` rule and a body that
332
+ is not JSON are described in [Validation with Standard Schema](../cordis/validation.md).
333
+
334
+ ### With Zod
335
+
336
+ You can use Zod with the schema validator:
337
+
338
+ **npm**
339
+
340
+ ```sh
341
+ npm i zod
342
+ ```
343
+
344
+ **yarn**
345
+
346
+ ```sh
347
+ yarn add zod
348
+ ```
349
+
350
+ **pnpm**
351
+
352
+ ```sh
353
+ pnpm add zod
354
+ ```
355
+
356
+ **bun**
357
+
358
+ ```sh
359
+ bun add zod
360
+ ```
361
+
362
+ ```ts
363
+ import * as z from 'zod'
364
+ import { schemaValidator } from '@acryldev/blends/schema-validator'
365
+
366
+ const schema = z.object({
367
+ name: z.string(),
368
+ age: z.number(),
369
+ })
370
+
371
+ app.post('/author', schemaValidator('json', schema), (c) => {
372
+ const data = c.req.valid('json')
373
+ return c.json({
374
+ success: true,
375
+ message: `${data.name} is ${data.age}`,
376
+ })
377
+ })
378
+ ```
379
+
380
+ ### With Valibot
381
+
382
+ [Valibot](https://valibot.dev/) is a lightweight alternative to Zod with a modular design:
383
+
384
+ **npm**
385
+
386
+ ```sh
387
+ npm i valibot
388
+ ```
389
+
390
+ **yarn**
391
+
392
+ ```sh
393
+ yarn add valibot
394
+ ```
395
+
396
+ **pnpm**
397
+
398
+ ```sh
399
+ pnpm add valibot
400
+ ```
401
+
402
+ **bun**
403
+
404
+ ```sh
405
+ bun add valibot
406
+ ```
407
+
408
+ ```ts
409
+ import * as v from 'valibot'
410
+ import { schemaValidator } from '@acryldev/blends/schema-validator'
411
+
412
+ const schema = v.object({
413
+ name: v.string(),
414
+ age: v.number(),
415
+ })
416
+
417
+ app.post('/author', schemaValidator('json', schema), (c) => {
418
+ const data = c.req.valid('json')
419
+ return c.json({
420
+ success: true,
421
+ message: `${data.name} is ${data.age}`,
422
+ })
423
+ })
424
+ ```
425
+
426
+ ### With ArkType
427
+
428
+ [ArkType](https://arktype.io/) offers TypeScript-native syntax for runtime validation:
429
+
430
+ **npm**
431
+
432
+ ```sh
433
+ npm i arktype
434
+ ```
435
+
436
+ **yarn**
437
+
438
+ ```sh
439
+ yarn add arktype
440
+ ```
441
+
442
+ **pnpm**
443
+
444
+ ```sh
445
+ pnpm add arktype
446
+ ```
447
+
448
+ **bun**
449
+
450
+ ```sh
451
+ bun add arktype
452
+ ```
453
+
454
+ ```ts
455
+ import { type } from 'arktype'
456
+ import { schemaValidator } from '@acryldev/blends/schema-validator'
457
+
458
+ const schema = type({
459
+ name: 'string',
460
+ age: 'number',
461
+ })
462
+
463
+ app.post('/author', schemaValidator('json', schema), (c) => {
464
+ const data = c.req.valid('json')
465
+ return c.json({
466
+ success: true,
467
+ message: `${data.name} is ${data.age}`,
468
+ })
469
+ })
470
+ ```
@@ -0,0 +1,60 @@
1
+ # Accepts Helper
2
+
3
+ Accepts Helper helps to handle Accept headers in the Requests.
4
+
5
+ ## Import
6
+
7
+ ```ts
8
+ import { Acryl } from '@acryldev/blends'
9
+ import { accepts } from '@acryldev/blends/accepts'
10
+ ```
11
+
12
+ ## `accepts()`
13
+
14
+ The `accepts()` function looks at the Accept header, such as Accept-Encoding and Accept-Language, and returns the proper value.
15
+
16
+ ```ts
17
+ import { accepts } from '@acryldev/blends/accepts'
18
+
19
+ app.get('/', (c) => {
20
+ const accept = accepts(c, {
21
+ header: 'Accept-Language',
22
+ supports: ['en', 'ja', 'zh'],
23
+ default: 'en',
24
+ })
25
+ return c.json({ lang: accept })
26
+ })
27
+ ```
28
+
29
+ ### `AcceptHeader` type
30
+
31
+ The definition of the `AcceptHeader` type is as follows.
32
+
33
+ ```ts
34
+ export type AcceptHeader =
35
+ | 'Accept'
36
+ | 'Accept-Charset'
37
+ | 'Accept-Encoding'
38
+ | 'Accept-Language'
39
+ | 'Accept-Patch'
40
+ | 'Accept-Post'
41
+ | 'Accept-Ranges'
42
+ ```
43
+
44
+ ## Options
45
+
46
+ ### **(required)** header: `AcceptHeader`
47
+
48
+ The target accept header.
49
+
50
+ ### **(required)** supports: `string[]`
51
+
52
+ The header values which your application supports.
53
+
54
+ ### **(required)** default: `string`
55
+
56
+ The default values.
57
+
58
+ ### *(optional)* match: `(accepts: Accept[], config: acceptsConfig) => string`
59
+
60
+ The custom match function.
@@ -0,0 +1,57 @@
1
+ # Adapter Helper
2
+
3
+ The Adapter Helper reads an app's environment the same way on every runtime it runs on.
4
+
5
+ ## Import
6
+
7
+ ```ts
8
+ import { Acryl } from '@acryldev/blends'
9
+ import { env, getRuntimeKey } from '@acryldev/blends/adapter'
10
+ ```
11
+
12
+ ## `env()`
13
+
14
+ The `env()` function returns the environment the host gives the app. On Node.js, the verified runtime, that is `process.env`; on Bun it is `Bun.env` (and `process.env`), and the two entries a `.env` file adds are there as well. A host that passes its own environment to `app.fetch(request, env)` gets that instead.
15
+
16
+ ```ts
17
+ import { env } from '@acryldev/blends/adapter'
18
+
19
+ app.get('/env', (c) => {
20
+ // NAME is process.env.NAME on Node.js and Bun
21
+ const { NAME } = env<{ NAME: string }>(c)
22
+ return c.text(NAME)
23
+ })
24
+ ```
25
+
26
+ ### Specify the runtime
27
+
28
+ `env()` reads the runtime itself. Pass the runtime key as the second argument when a host embeds the app and detects it differently, or in a test that fixes the key:
29
+
30
+ ```ts
31
+ app.get('/env', (c) => {
32
+ const { NAME } = env<{ NAME: string }>(c, 'node')
33
+ return c.text(NAME)
34
+ })
35
+ ```
36
+
37
+ ## `getRuntimeKey()`
38
+
39
+ The `getRuntimeKey()` function returns the identifier of the current runtime.
40
+
41
+ ```ts
42
+ app.get('/', (c) => {
43
+ if (getRuntimeKey() === 'bun') {
44
+ return c.text('You are on Bun')
45
+ }
46
+ return c.text(`You are on ${getRuntimeKey()}`)
47
+ })
48
+ ```
49
+
50
+ ### Available runtime keys
51
+
52
+ The keys follow [WinterCG's Runtime Keys proposal](https://runtime-keys.proposal.wintercg.org/):
53
+
54
+ - `node` - Node.js, the verified runtime
55
+ - `bun` - Bun, experimental
56
+ - `deno`, `workerd`, `edge-light`, `fastly` - keys the helper still recognizes for a host that embeds an app in that runtime; 1.0 ships no adapter for them (see [Other runtimes](../getting-started/other-runtimes.md))
57
+ - `other` - a runtime the helper does not recognize