@tinkered/core 0.30.0 → 0.31.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.30.0",
3
+ "version": "0.31.0",
4
4
  "description": "Tinkered core: a small, fast reactive/graph dependency engine.",
5
5
  "keywords": [
6
6
  "tanstack-intent"
@@ -14,7 +14,7 @@ metadata:
14
14
  task skill to load next.
15
15
  type: core
16
16
  library: '@tinkered/core'
17
- library_version: '0.30.0'
17
+ library_version: '0.31.0'
18
18
  sources:
19
19
  - 'lagz0ne/tinkered:packages/core/src/main.ts'
20
20
  - 'lagz0ne/tinkered:docs/best-practices.md'
@@ -34,7 +34,7 @@ the task crosses two of them.
34
34
  [operation](./operation/SKILL.md)
35
35
  - State, keyed members, where a write lands:
36
36
  [data](./data/SKILL.md)
37
- - A feature's one door, config, install:
37
+ - A feature's capsule, config, install:
38
38
  [capsule](./capsule/SKILL.md)
39
39
  - A call or a live read between server and page:
40
40
  [rpc](./rpc/SKILL.md)
@@ -78,8 +78,9 @@ id, fix the code, and run the check again.
78
78
  - `tinker/config`: config goes in the capsule
79
79
  call. Check: `MissingConfig` at start.
80
80
  Skill: capsule.
81
- - `tinker/one-door`: reach a feature as
82
- `@/<feature>`. Check: lint. Skill: capsule.
81
+ - `tinker/barrel`: a file exports only what it
82
+ declares. Check: `tinker check`. Skill:
83
+ capsule.
83
84
  - `tinker/cell-write`: an exported cell is read
84
85
  only. Check: lint and `InvalidDependency`.
85
86
  Skill: data.
@@ -5,7 +5,7 @@ description: >
5
5
  give it settings, install it in a cmd, or
6
6
  import it from other code. Also when start
7
7
  fails with MissingConfig, or a check prints
8
- tinker/seam, tinker/config or tinker/one-door.
8
+ tinker/seam, tinker/config or tinker/barrel.
9
9
  metadata:
10
10
  purpose: >
11
11
  How to write a capsule, fill its config in
@@ -13,7 +13,7 @@ metadata:
13
13
  binding only.
14
14
  type: sub-skill
15
15
  library: '@tinkered/core'
16
- library_version: '0.30.0'
16
+ library_version: '0.31.0'
17
17
  requires:
18
18
  - core
19
19
  sources:
@@ -23,9 +23,8 @@ sources:
23
23
 
24
24
  # Capsule
25
25
 
26
- A capsule is a feature's one door. It holds the
27
- feature's config, its exports and its hooks. A cmd
28
- installs it with values.
26
+ A capsule holds a feature's config, its exports
27
+ and its hooks. A cmd installs it with values.
29
28
 
30
29
  ## Setup
31
30
 
@@ -107,19 +106,6 @@ export default defineMain(async ({ env, signal }) => {
107
106
  function builds it.
108
107
  - A feature never reads `process.env`.
109
108
 
110
- ### One folder, one door
111
-
112
- ```text
113
- src/sea/
114
- index.ts the capsule
115
- index.server.ts the server's door
116
- contract.ts rpc and remote data
117
- ```
118
-
119
- Other features import `@/sea` only. They reach a
120
- unit as `sea.press`, never by a path into the
121
- folder.
122
-
123
109
  ## Common mistakes
124
110
 
125
111
  ### HIGH: root tags fill a capsule key [tinker/config]
@@ -152,17 +138,27 @@ const press = operation({
152
138
  Right: declare a `config` key, and let the cmd
153
139
  pass the value.
154
140
 
155
- ### HIGH: an import past the door [tinker/one-door]
141
+ ### HIGH: a barrel [tinker/barrel]
142
+
143
+ A barrel passes on what other files export. Its
144
+ importer cannot see which files it reaches. One
145
+ of them can be a `.server.` file, and then the
146
+ page build takes server code.
156
147
 
157
148
  Wrong:
158
149
 
159
150
  ```ts no-check
160
- import { waves } from "@/sea/contract";
151
+ export * from "./todo-list";
152
+ export type { Todo } from "./todo.schema";
161
153
  ```
162
154
 
163
- Right: `import { sea } from "@/sea";` then
164
- `sea.waves`. The lint rule
165
- `no-restricted-imports` finds the wrong form.
155
+ Right: delete the re-export. Import the name from
156
+ the file that declares it, as
157
+ `import { TodoList } from "@/todo/todo-list";`.
158
+ A file exports only what it declares.
159
+
160
+ Check: `tinker check` prints each re-export and
161
+ its line.
166
162
 
167
163
  ### MEDIUM: a function that makes units
168
164
 
@@ -175,6 +171,5 @@ config.
175
171
  ## Completion
176
172
 
177
173
  - The app starts: no `MissingConfig`.
178
- - `bun run check:style` prints no
179
- `no-restricted-imports`.
174
+ - `tinker check` prints no `tinker/barrel`.
180
175
  - `grep -rn "process.env" src` prints no line.
@@ -13,7 +13,7 @@ metadata:
13
13
  cell read only.
14
14
  type: sub-skill
15
15
  library: '@tinkered/core'
16
- library_version: '0.30.0'
16
+ library_version: '0.31.0'
17
17
  requires:
18
18
  - core
19
19
  sources:
@@ -4,8 +4,9 @@ description: >
4
4
  Use when you add or change an action in a
5
5
  Tinker app: its label, input shape, deps, run
6
6
  body, how to call it, or how it fails. Also
7
- when a check prints tinker/plain or
8
- tinker/floating, or for a Workflow SDK flow.
7
+ when a check prints tinker/plain,
8
+ tinker/floating or tinker/graph, or for a
9
+ Workflow SDK flow.
9
10
  metadata:
10
11
  purpose: >
11
12
  How to write, call and fail an operation,
@@ -13,7 +14,7 @@ metadata:
13
14
  allowed in app code.
14
15
  type: sub-skill
15
16
  library: '@tinkered/core'
16
- library_version: '0.30.0'
17
+ library_version: '0.31.0'
17
18
  requires:
18
19
  - core
19
20
  sources:
@@ -212,6 +213,51 @@ scope.run(press, { input: { x: 1, y: 2 } });
212
213
  Right: `await scope.run(...)`, or keep the
213
214
  promise and await it later.
214
215
 
216
+ ### HIGH: the code graph differs from tinker.graph [tinker/graph]
217
+
218
+ `tinker.graph` holds one line per operation: its
219
+ exits, and the cells and operations its `run`
220
+ reads, writes and calls. The lines are facts.
221
+ `tinker check` builds them from the code. Each
222
+ line that differs from the file is a finding.
223
+
224
+ The finding never judges the change. You judge
225
+ it.
226
+
227
+ An empty set means "none". A `?` means the graph
228
+ could not see: a dep handed on (passed to a
229
+ function, put in an array, given another name),
230
+ the deps handed on whole, a call it does not
231
+ know, a dep it cannot name (a capsule or contract
232
+ member, a label not written as a string, an
233
+ `atScope` controller), a tag that holds a unit,
234
+ or a `run` passed by name. A tag that holds a
235
+ union of unit kinds, or a held cell that `run`
236
+ never uses, may show no `?`.
237
+
238
+ The graph reads each op's own body. A resource's
239
+ own code is not read: a write inside a
240
+ resource's value does not show.
241
+
242
+ Wrong: a move now writes a cell it did not, and
243
+ nobody read that.
244
+
245
+ ```ts no-check
246
+ list.set({ ...now, state: input.state });
247
+ audit.set({ id: input.id, by: me });
248
+ ```
249
+
250
+ ```text
251
+ issue.move.do: writes{issues.audit.set,
252
+ issues.list.set}, tinker.graph says
253
+ writes{issues.list.set}
254
+ ```
255
+
256
+ Right: read the change. If you meant it, run
257
+ `tinker graph --write` and commit the file. The
258
+ reviewer reads its diff. If you did not mean it,
259
+ fix the code.
260
+
215
261
  ### MEDIUM: `Date.now()` or `Math.random()` in a run
216
262
 
217
263
  The run then gives a new answer in each test. Use
@@ -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.30.0'
16
+ library_version: '0.31.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.30.0'
15
+ library_version: '0.31.0'
16
16
  requires:
17
17
  - core
18
18
  sources: