@trainheroic-unofficial/dto 0.4.2 → 0.5.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 (2) hide show
  1. package/README.md +35 -11
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -6,17 +6,35 @@ their types from here instead of redefining them.
6
6
 
7
7
  Part of the [trainheroic-unofficial](../../README.md) workspace.
8
8
 
9
+ ## Contents
10
+
11
+ - [Install](#install)
12
+ - [What's inside](#whats-inside)
13
+ - [Develop](#develop)
14
+
9
15
  ## Install
10
16
 
11
- Internal to the workspace (consumed as `workspace:*`). Published builds expose a single ESM
12
- entry with type declarations.
17
+ Published to npm as a single ESM entry with type declarations; other packages in this
18
+ workspace depend on it via `workspace:*`. You can install it on its own:
19
+
20
+ ```bash
21
+ npm install @trainheroic-unofficial/dto
22
+ ```
23
+
24
+ It depends on [zod](https://zod.dev) (v4), pulled in automatically as a dependency. Each schema
25
+ travels with its inferred type, so you validate and type from one import. `.parse()` throws a `ZodError` on bad data; use
26
+ `.safeParse()` if you want a result object instead.
13
27
 
14
28
  ```ts
15
- import { workoutSpecSchema, type WorkoutSpec, idSchema } from "@trainheroic-unofficial/dto";
29
+ import { workoutSpecSchema, type WorkoutSpec } from "@trainheroic-unofficial/dto";
16
30
 
31
+ // `input` is untrusted data (e.g. a parsed JSON file or request body).
17
32
  const spec: WorkoutSpec = workoutSpecSchema.parse(input);
18
33
  ```
19
34
 
35
+ It imports no `node:*` and touches no filesystem, so it runs anywhere — Node, browsers, and
36
+ Cloudflare workerd.
37
+
20
38
  ## What's inside
21
39
 
22
40
  Schemas come in two flavors. Input schemas are strict enough to validate user-supplied
@@ -28,17 +46,23 @@ for ids, so upstream API drift adds fields without breaking parsing.
28
46
  re-exported through `index.ts`. The central pieces:
29
47
 
30
48
  - `idSchema` normalizes the API's number-or-string ids.
31
- - `workoutSpecSchema` / `WorkoutSpec` is the protocol used to build a session: an optional
32
- top-level instruction plus an array of blocks, where each block carries an exercises
33
- array and each exercise references a library id. `blockSpecSchema` and
34
- `exerciseSpecSchema` are its parts; `leaderboardSpecSchema` covers red-zone leaderboards.
35
- - The read-back types (`ReadResult` and friends) describe a decoded session, and `Advisory`
36
- carries the unit notes and warnings the encoder produces.
37
- - The `responses` module holds the tolerant schemas used to validate API payloads at
38
- checkpoints without rejecting unknown fields.
49
+ - `workoutSpecSchema` / `WorkoutSpec` is the input you hand to the SDK's workout encoder (the
50
+ code in `js` that turns a spec into TrainHeroic's payload): an optional top-level
51
+ instruction plus an array of blocks, where each block carries an exercises array and each
52
+ exercise references an exercise-library id. `blockSpecSchema` and `exerciseSpecSchema` are
53
+ its parts; `leaderboardSpecSchema` covers Red Zone leaderboards (TrainHeroic's competitive
54
+ block type, where athletes are ranked on a score).
55
+ - The read-back types (`ReadResult`, `ReadBlock`, `ReadExercise`) describe a session decoded
56
+ back out of the API into a readable shape, and `Advisory` carries the unit notes and
57
+ warnings the encoder emits (for example, a prescription whose unit does not match the
58
+ exercise's parameter type).
59
+ - The `responses` module holds the tolerant schemas the SDK uses to sanity-check an API
60
+ response before trusting it, without rejecting unknown fields.
39
61
 
40
62
  ## Develop
41
63
 
64
+ Run `pnpm install` once at the repo root (Node >= 22, pnpm 10), then from this package:
65
+
42
66
  ```bash
43
67
  pnpm build # tsdown -> dist (ESM + .d.mts)
44
68
  pnpm typecheck
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/dto",
3
- "version": "0.4.2",
3
+ "version": "0.5.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",