Skip to content

docs(modifiers): document attachModifier and unlockrequest - #108

Merged
Upd4ting merged 1 commit into
mainfrom
docs/ant-1815
Nov 10, 2026
Merged

Upd4ting merged 1 commit into
mainfrom
docs/ant-1815

Conversation

@Upd4ting

Copy link
Copy Markdown
Member

Why

A custom-modifier author calling attachModifier or unlockrequest saw bare parameter types. #71 changed what both take, and the contract it settled lived only in that PR's body. This PR puts that contract in TSDoc on both functions and makes the "Create custom modifiers" docs page agree with it. #48 is closed, so the TSDoc describes the signatures on main.

What

  • attachModifier TSDoc gives each parameter, what TypeScript checks (options only, not that field names a member), what happens at run time (accessor for a modifier with lock, event handlers for every other method), and both throws: constructor or __proto__, and a modifier with lock stacked on a field that already has a one-way modifier.
  • unlockrequest TSDoc gives each parameter, that table is read only for its modifier metadata, what the expression yields for one-way and unmodified fields, and that it throws a TypeError when modifiers has no entry for a two-way modifier on the field.
  • docs/3.table-modifiers.md gains "Attach a modifier" and "Read a modified field in a query", which state the same contract.

No code changes. The skill file already states the stacking rule and needs no edit.

Proof

Runtime probe against the built dist/modifiers/common.js, checking each throw and pass case the TSDoc names:

unlockrequest missing entry -> TypeError: args[id] is not iterable (cannot read property undefined)
unlockrequest with entry -> ok
attach on constructor -> Error: Cannot add Modifier Two on T.constructor: the field would replace the class constructor that locates the metadata of every instance.
attach after one-way -> Error: Adding Modifier Two on T.b after a One-Way Modifier, please review your ordering.
events-only after one-way -> ok

Documentation check (tooling-configs v0.0.9):

Docs: 6 files, 21 local links, 0 compatibility tables, 3 checked examples, 0 API pages; 0 failures.

pnpm run checks:

Checks: 9 passed, 0 failed.

antelopejs-comment-proof origin/main:

Comment proof: 2 packages, 37 entries unchanged against origin/main (committed HEAD).

Suppressions in authored code files (origin/main and committed HEAD). A lint directive counts once per rule it names; * is a directive naming none.

Suppressions base HEAD
Lint suppressions, all rules 28 28
Lint suppressions, anti-slop/no-unknown-parameters 8 8
Lint suppressions, anti-slop/no-unknown-returns 1 1
Lint suppressions, anti-slop/no-unsafe-dictionary-type 10 10
Lint suppressions, typescript/no-unnecessary-type-parameters 4 4
Lint suppressions, typescript/no-unsafe-assignment 2 2
Lint suppressions, typescript/no-unsafe-return 3 3
@ts-expect-error 0 0
@ts-ignore 0 0
SAFETY: comments 8 8
Lint config rule-offs, all rules 0 0

@Upd4ting
Upd4ting merged commit 8a00b59 into main Nov 10, 2026
7 checks passed
@Upd4ting
Upd4ting deleted the docs/ant-1815 branch November 10, 2026 15:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant