@tinkered/core 0.25.0 → 0.26.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinkered/core",
3
- "version": "0.25.0",
3
+ "version": "0.26.0",
4
4
  "description": "Tinkered core: a small, fast reactive/graph dependency engine.",
5
5
  "keywords": [
6
6
  "tanstack-intent"
@@ -5,7 +5,8 @@ description: >
5
5
  @tinkered/core: an operation, a data cell, a
6
6
  resource, a capsule, rpc, remote data, or a
7
7
  test of them. Start here, then load one task
8
- skill.
8
+ skill. Also when a check prints tinker/cast
9
+ or tinker/gap.
9
10
  metadata:
10
11
  purpose: >
11
12
  Entry skill for Tinker Core. It names the
@@ -13,7 +14,7 @@ metadata:
13
14
  task skill to load next.
14
15
  type: core
15
16
  library: '@tinkered/core'
16
- library_version: '0.25.0'
17
+ library_version: '0.26.0'
17
18
  sources:
18
19
  - 'lagz0ne/tinkered:packages/core/src/main.ts'
19
20
  - 'lagz0ne/tinkered:docs/best-practices.md'
@@ -85,19 +86,92 @@ id, fix the code, and run the check again.
85
86
  - `tinker/plain`: every named function is an
86
87
  operation. A Workflow SDK workflow or step in a
87
88
  `*.flow.ts` file passes. Check:
88
- `bun run check:plain`. Skill: operation.
89
+ `tinker check`. Skill: operation.
89
90
  - `tinker/floating`: a root answers each call
90
91
  with a promise; await it. Check: lint
91
92
  `no-floating-promises`. Skill: operation.
92
93
 
93
- The page rules (`tinker/react-state`,
94
- `tinker/one-wire`) are in the `@tinkered/react`
95
- skill.
94
+ - `tinker/cast`: no `as` but `as const`, no `!`,
95
+ no `any`. Check: `tinker check`. Skill: this
96
+ one.
97
+ - `tinker/gap`: a gap marker sits on an open row
98
+ of the app's gaps doc. Check: `tinker check`.
99
+ Skill: this one.
100
+
101
+ The page rules (`tinker/kind`,
102
+ `tinker/react-state`, `tinker/one-wire`,
103
+ `tinker/keyed-prop`) are in the
104
+ `@tinkered/react` skill.
105
+
106
+ ## Common mistakes
107
+
108
+ ### HIGH: a cast [tinker/cast]
109
+
110
+ A cast tells the checker to trust you. Then a
111
+ wrong value gets through: `value as never` sends
112
+ any string to the server.
113
+
114
+ Wrong:
115
+
116
+ ```ts no-check
117
+ const state = form.get("state") as State;
118
+ const issue = data!.issue;
119
+ const raw: any = message;
120
+ ```
121
+
122
+ Right: narrow or parse. Do not cast:
123
+
124
+ - a form field: `new FormData(form).get("x")`,
125
+ then `typeof value === "string"`;
126
+ - a value of a list: find it in the list,
127
+ `states.find((s) => s === value)`;
128
+ - a fault: `api.fault.is(error)`;
129
+ - a payload: `schema.safeParse(payload)`;
130
+ - a value that can be absent: `if (value)`;
131
+ - a cast you cannot remove yet: a gap row and
132
+ its marker, never a `lint-disable` comment.
133
+
134
+ `as const` is not a cast. It may stay.
135
+
136
+ ### HIGH: a gap marker off its row [tinker/gap]
137
+
138
+ Wrong:
139
+
140
+ ```ts no-check
141
+ // tinker-gap: G9
142
+ fetch("/auth");
143
+ ```
144
+
145
+ Right: put the marker on the line above the
146
+ finding. Name an open row of the gaps doc. Keep
147
+ the marked lines within the row's `Lines:` count.
148
+ Better: fix the finding and remove the marker.
149
+
150
+ ### HIGH: a gate off by a `lint-disable` comment [tinker/gap]
151
+
152
+ The comment hides the cast or the missing case
153
+ from the check. Nobody counts it.
154
+
155
+ Wrong:
156
+
157
+ ```ts no-check
158
+ // eslint-disable-next-line no-non-null-assertion
159
+ const issue = data!.issue;
160
+ ```
161
+
162
+ Right: remove the comment and fix the line. When
163
+ it cannot be fixed yet, mark it with a gap row:
164
+ `// tinker-gap: G<n>` on the line above, and a
165
+ row `## G<n>: <why>` in the gaps doc that
166
+ `tinker.json` names, with `- Status: open` and
167
+ `- Lines: <count>`.
96
168
 
97
169
  ## Completion
98
170
 
99
- 1. Run the app's `bun run check`.
100
- 2. Run `bun run check:plain`.
101
- 3. For each id a check prints, load its skill.
171
+ 1. Run `tinker check`.
172
+ 2. For each finding, do what its fix says. To
173
+ read more, load the skill it names.
174
+ 3. Run `tinker check` again.
102
175
 
103
- A typecheck alone does not prove the rules.
176
+ Only `tinker check: OK` with exit 0 says that the
177
+ work is done.
@@ -13,7 +13,7 @@ metadata:
13
13
  binding only.
14
14
  type: sub-skill
15
15
  library: '@tinkered/core'
16
- library_version: '0.25.0'
16
+ library_version: '0.26.0'
17
17
  requires:
18
18
  - core
19
19
  sources:
@@ -13,7 +13,7 @@ metadata:
13
13
  cell read only.
14
14
  type: sub-skill
15
15
  library: '@tinkered/core'
16
- library_version: '0.25.0'
16
+ library_version: '0.26.0'
17
17
  requires:
18
18
  - core
19
19
  sources:
@@ -13,7 +13,7 @@ metadata:
13
13
  allowed in app code.
14
14
  type: sub-skill
15
15
  library: '@tinkered/core'
16
- library_version: '0.25.0'
16
+ library_version: '0.26.0'
17
17
  requires:
18
18
  - core
19
19
  sources:
@@ -160,7 +160,7 @@ function nextHue(seed: number) {
160
160
  Right: make it an operation and name it in
161
161
  `depends`, as `double` above.
162
162
 
163
- Check: `bun run check:plain` prints the file and
163
+ Check: `tinker check` prints the file and
164
164
  the line of each plain function.
165
165
 
166
166
  ### HIGH: a helper behind a callback [tinker/plain]
@@ -184,7 +184,7 @@ closure: a function that reads a name of the
184
184
  function around it, such as a counter of its
185
185
  resource.
186
186
 
187
- Check: `bun run check:plain` prints the helper
187
+ Check: `tinker check` prints the helper
188
188
  and the line that calls it.
189
189
 
190
190
  ### HIGH: `name` in place of `label`
@@ -220,7 +220,7 @@ argument.
220
220
 
221
221
  ## Completion
222
222
 
223
- - `bun run check:plain` prints no line.
223
+ - `tinker check` prints `tinker check: OK`.
224
224
  - The lint prints no `no-floating-promises`.
225
225
  - A test calls the operation through a scope.
226
226
  Read [testing](../testing/SKILL.md).
@@ -13,7 +13,7 @@ metadata:
13
13
  on the client with remote data.
14
14
  type: sub-skill
15
15
  library: '@tinkered/core'
16
- library_version: '0.25.0'
16
+ library_version: '0.26.0'
17
17
  requires:
18
18
  - core
19
19
  - capsule
@@ -12,7 +12,7 @@ metadata:
12
12
  and join two scopes with the memory backend.
13
13
  type: sub-skill
14
14
  library: '@tinkered/core'
15
- library_version: '0.25.0'
15
+ library_version: '0.26.0'
16
16
  requires:
17
17
  - core
18
18
  sources: