Skip to content

Commit cdb1246

Browse files
lambdalisuelambdalisue
committed
docs: update api docs
1 parent a31cc4d commit cdb1246

25 files changed

Lines changed: 4317 additions & 4286 deletions

‎data/api/builder.json‎

Lines changed: 35 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
{
22
"name": "builder",
33
"specifier": "@probitas/builder",
4-
"version": "0.3.1",
4+
"version": "0.3.2",
55
"moduleDoc": "Builder module for creating scenario definitions with a fluent, type-safe API.\n\nThis package provides the {@linkcode scenario} fn function that returns a builder\nfor constructing scenario definitions. The builder uses method chaining to define\nresources, setup functions, and test steps with full TypeScript type inference.\n\n## Links\n\n- [GitHub Repository](https://github.com/jsr-probitas/probitas)\n- [@probitas/probitas](https://jsr.io/@probitas/probitas) - Main package (recommended for most users)\n\n## Related Packages\n\n| Package | Description |\n|---------|-------------|\n| [@probitas/core](https://jsr.io/@probitas/core) | Core type definitions used by this builder |\n| [@probitas/runner](https://jsr.io/@probitas/runner) | Executes scenarios built with this package |\n\n## Key Features\n\n- **Fluent API**: Chain methods naturally to build complex scenarios\n- **Type-safe context**: Each step receives typed access to previous step results\n- **Resource management**: Register resources with automatic lifecycle handling\n- **Setup/Cleanup**: Define setup functions with automatic cleanup support\n- **Configurable defaults**: Override timeout and retry settings at any level\n\n## Core Exports\n\n- {@linkcode scenario} - Factory function to create a new scenario builder\n- {@linkcode StepContext} - Type representing the context passed to step functions\n- {@linkcode StepFunction} - Type signature for step functions\n- {@linkcode SetupFunction} - Type signature for setup functions\n- {@linkcode ResourceFunction} - Type signature for resource fn functions\n- {@linkcode BuilderScenarioOptions} - Partial options for scenario configuration\n- {@linkcode BuilderStepOptions} - Partial options for step configuration\n- {@linkcode DEFAULT_SCENARIO_OPTIONS} - Default values for scenario options\n- {@linkcode DEFAULT_STEP_OPTIONS} - Default values for step options\n",
66
"exports": [
77
{
88
"name": "scenario",
99
"isDefault": false,
1010
"location": {
11-
"filename": "https://jsr.io/@probitas/builder/0.3.1/scenario_builder.ts",
12-
"line": 571,
11+
"filename": "https://jsr.io/@probitas/builder/0.3.2/scenario_builder.ts",
12+
"line": 644,
1313
"col": 0,
14-
"byteIndex": 18358
14+
"byteIndex": 20517
1515
},
1616
"declarationKind": "export",
1717
"jsDoc": {
@@ -37,15 +37,15 @@
3737
},
3838
{
3939
"kind": "example",
40-
"doc": "Basic scenario with type-safe step chaining\n```ts\nimport { scenario } from \"@probitas/builder\";\n\nexport default scenario(\"User Registration\")\n .step(\"Create user\", async () => {\n const user = await createUser({ email: \"test@example.com\" });\n return { userId: user.id };\n })\n .step(\"Verify email\", async (ctx) => {\n // ctx.previous is typed as { userId: string }\n await verifyEmail(ctx.previous.userId);\n })\n .build();\n```\n"
40+
"doc": "Basic scenario with type-safe step chaining\n```ts\nimport { scenario } from \"@probitas/builder\";\n\n// Mock user service for example\nconst createUser = (_data: { email: string }) =>\n Promise.resolve({ id: \"user-123\" });\nconst verifyEmail = (_userId: string) => Promise.resolve();\n\nexport default scenario(\"User Registration\")\n .step(\"Create user\", async () => {\n const user = await createUser({ email: \"test@example.com\" });\n return { userId: user.id };\n })\n .step(\"Verify email\", async (ctx) => {\n // ctx.previous is typed as { userId: string }\n await verifyEmail(ctx.previous.userId);\n })\n .build();\n```\n"
4141
},
4242
{
4343
"kind": "example",
44-
"doc": "Scenario with tags for filtering\n```ts\nscenario(\"Payment Integration\", {\n tags: [\"integration\", \"payment\", \"slow\"],\n stepOptions: { timeout: 60000 } // 1 minute timeout for all steps\n})\n .step(\"Process payment\", async () => { ... })\n .build();\n\n// Run with: probitas run -s \"tag:payment\"\n```\n"
44+
"doc": "Scenario with tags for filtering\n```ts\nimport { scenario } from \"@probitas/builder\";\n\nscenario(\"Payment Integration\", {\n tags: [\"integration\", \"payment\", \"slow\"],\n stepOptions: { timeout: 60000 } // 1 minute timeout for all steps\n})\n .step(\"Process payment\", async () => {\n return { success: true };\n })\n .build();\n\n// Run with: probitas run -s \"tag:payment\"\n```\n"
4545
},
4646
{
4747
"kind": "example",
48-
"doc": "Scenario with resources and setup\n```ts\nscenario(\"Database Test\")\n .resource(\"db\", async () => await Database.connect())\n .setup((ctx) => {\n // Run migrations\n return () => ctx.resources.db.rollback();\n })\n .step(\"Insert data\", (ctx) => ctx.resources.db.insert(...))\n .step(\"Query data\", (ctx) => ctx.resources.db.query(...))\n .build();\n```\n"
48+
"doc": "Scenario with resources and setup\n```ts\nimport { scenario } from \"@probitas/builder\";\n\n// Mock Database for example\nconst Database = {\n connect: () =>\n Promise.resolve({\n rollback: () => {},\n insert: (_data: { id: number }) => {},\n query: (_sql: string) => [{ id: 1 }],\n }),\n};\n\nscenario(\"Database Test\")\n .resource(\"db\", async () => await Database.connect())\n .setup((ctx) => {\n // Run migrations\n return () => ctx.resources.db.rollback();\n })\n .step(\"Insert data\", (ctx) => ctx.resources.db.insert({ id: 1 }))\n .step(\"Query data\", (ctx) => ctx.resources.db.query(\"SELECT * FROM users\"))\n .build();\n```\n"
4949
},
5050
{
5151
"kind": "see",
@@ -102,10 +102,10 @@
102102
"name": "BuilderStepContext",
103103
"isDefault": false,
104104
"location": {
105-
"filename": "https://jsr.io/@probitas/builder/0.3.1/types.ts",
106-
"line": 40,
105+
"filename": "https://jsr.io/@probitas/builder/0.3.2/types.ts",
106+
"line": 44,
107107
"col": 0,
108-
"byteIndex": 1233
108+
"byteIndex": 1337
109109
},
110110
"declarationKind": "export",
111111
"jsDoc": {
@@ -128,11 +128,11 @@
128128
},
129129
{
130130
"kind": "example",
131-
"doc": "Accessing previous result\n```ts\nscenario(\"Chained Steps\")\n .step(\"First\", () => ({ id: 123 }))\n .step(\"Second\", (ctx) => {\n console.log(ctx.previous.id); // 123 (typed as number)\n })\n .build();\n```\n"
131+
"doc": "Accessing previous result\n```ts\nimport { scenario } from \"@probitas/builder\";\n\nscenario(\"Chained Steps\")\n .step(\"First\", () => ({ id: 123 }))\n .step(\"Second\", (ctx) => {\n console.log(ctx.previous.id); // 123 (typed as number)\n })\n .build();\n```\n"
132132
},
133133
{
134134
"kind": "example",
135-
"doc": "Using shared store\n```ts\nscenario(\"Store Example\")\n .setup((ctx) => {\n ctx.store.set(\"startTime\", Date.now());\n })\n .step(\"Check duration\", (ctx) => {\n const start = ctx.store.get(\"startTime\") as number;\n console.log(`Elapsed: ${Date.now() - start}ms`);\n })\n .build();\n```"
135+
"doc": "Using shared store\n```ts\nimport { scenario } from \"@probitas/builder\";\n\nscenario(\"Store Example\")\n .setup((ctx) => {\n ctx.store.set(\"startTime\", Date.now());\n })\n .step(\"Check duration\", (ctx) => {\n const start = ctx.store.get(\"startTime\") as number;\n console.log(`Elapsed: ${Date.now() - start}ms`);\n })\n .build();\n```"
136136
}
137137
]
138138
},
@@ -163,10 +163,10 @@
163163
"doc": "Result from the previous step.\n\nFully typed based on what the previous step returned.\nFor the first step, this is `unknown`."
164164
},
165165
"location": {
166-
"filename": "https://jsr.io/@probitas/builder/0.3.1/types.ts",
167-
"line": 51,
166+
"filename": "https://jsr.io/@probitas/builder/0.3.2/types.ts",
167+
"line": 55,
168168
"col": 2,
169-
"byteIndex": 1574
169+
"byteIndex": 1678
170170
},
171171
"params": [],
172172
"readonly": true,
@@ -185,13 +185,13 @@
185185
{
186186
"name": "results",
187187
"jsDoc": {
188-
"doc": "All accumulated results as a typed tuple.\n\nAllows accessing any previous result by index:\n```ts\nctx.results[0] // First step's result\nctx.results[1] // Second step's result\n```"
188+
"doc": "All accumulated results as a typed tuple.\n\nAllows accessing any previous result by index:\n- `ctx.results[0]` - First step's result\n- `ctx.results[1]` - Second step's result"
189189
},
190190
"location": {
191-
"filename": "https://jsr.io/@probitas/builder/0.3.1/types.ts",
192-
"line": 62,
191+
"filename": "https://jsr.io/@probitas/builder/0.3.2/types.ts",
192+
"line": 64,
193193
"col": 2,
194-
"byteIndex": 1824
194+
"byteIndex": 1912
195195
},
196196
"params": [],
197197
"readonly": true,
@@ -210,13 +210,13 @@
210210
{
211211
"name": "resources",
212212
"jsDoc": {
213-
"doc": "Named resources registered with `.resource()`.\n\nResources are typed based on their registration:\n```ts\n.resource(\"db\", () => createDbConnection())\n.step((ctx) => ctx.resources.db.query(...))\n```"
213+
"doc": "Named resources registered with `.resource()`.\n\nResources are typed based on their registration:\n```ts\nimport { scenario } from \"@probitas/builder\";\n\n// Mock database connection for example\nconst createDbConnection = () => ({ query: (_sql: string) => [{ id: 1 }] });\n\nscenario(\"test\")\n .resource(\"db\", () => createDbConnection())\n .step((ctx) => ctx.resources.db.query(\"SELECT 1\"))\n .build();\n```"
214214
},
215215
"location": {
216-
"filename": "https://jsr.io/@probitas/builder/0.3.1/types.ts",
217-
"line": 73,
216+
"filename": "https://jsr.io/@probitas/builder/0.3.2/types.ts",
217+
"line": 82,
218218
"col": 2,
219-
"byteIndex": 2089
219+
"byteIndex": 2415
220220
},
221221
"params": [],
222222
"readonly": true,
@@ -331,10 +331,10 @@
331331
"name": "BuilderStepFunction",
332332
"isDefault": false,
333333
"location": {
334-
"filename": "https://jsr.io/@probitas/builder/0.3.1/types.ts",
335-
"line": 102,
334+
"filename": "https://jsr.io/@probitas/builder/0.3.2/types.ts",
335+
"line": 117,
336336
"col": 0,
337-
"byteIndex": 2903
337+
"byteIndex": 3428
338338
},
339339
"declarationKind": "export",
340340
"jsDoc": {
@@ -362,11 +362,11 @@
362362
},
363363
{
364364
"kind": "example",
365-
"doc": "Sync step returning data\n```ts\nconst step: StepFunction<{ name: string }> = (ctx) => {\n return { name: \"Alice\" };\n};\n```\n"
365+
"doc": "Sync step returning data\n```ts\nimport type { BuilderStepFunction } from \"@probitas/builder\";\n\nconst step: BuilderStepFunction<{ name: string }> = (_ctx) => {\n return { name: \"Alice\" };\n};\n```\n"
366366
},
367367
{
368368
"kind": "example",
369-
"doc": "Async step with API call\n```ts\nconst step: StepFunction<User> = async (ctx) => {\n const response = await fetch(\"/api/user\", { signal: ctx.signal });\n return response.json();\n};\n```"
369+
"doc": "Async step with API call\n```ts\nimport type { BuilderStepFunction } from \"@probitas/builder\";\n\ntype User = { id: string; name: string };\n\nconst step: BuilderStepFunction<User> = async (ctx) => {\n const response = await fetch(\"/api/user\", { signal: ctx.signal });\n return response.json();\n};\n```"
370370
}
371371
]
372372
},
@@ -551,10 +551,10 @@
551551
"name": "BuilderStepDefinition",
552552
"isDefault": false,
553553
"location": {
554-
"filename": "https://jsr.io/@probitas/builder/0.3.1/types.ts",
555-
"line": 124,
554+
"filename": "https://jsr.io/@probitas/builder/0.3.2/types.ts",
555+
"line": 139,
556556
"col": 0,
557-
"byteIndex": 3678
557+
"byteIndex": 4203
558558
},
559559
"declarationKind": "export",
560560
"jsDoc": {
@@ -613,10 +613,10 @@
613613
"doc": "Step function to execute"
614614
},
615615
"location": {
616-
"filename": "https://jsr.io/@probitas/builder/0.3.1/types.ts",
617-
"line": 131,
616+
"filename": "https://jsr.io/@probitas/builder/0.3.2/types.ts",
617+
"line": 146,
618618
"col": 2,
619-
"byteIndex": 3918
619+
"byteIndex": 4443
620620
},
621621
"params": [],
622622
"readonly": true,
@@ -768,6 +768,5 @@
768768
]
769769
}
770770
}
771-
],
772-
"generatedAt": "2025-12-16T18:17:30.878Z"
771+
]
773772
}

0 commit comments

Comments
 (0)