WIP: docs: add type narrowing section and fix delayed state description #1

Closed

Copilot wants to merge 4 commits from copilot/add-readme-examples-sync-lazy into main

Copilot commented

2026-03-17 15:15:35 +00:00

(Migrated from github.com)

The readme incorrectly described delayed states as always-async, and lacked any documentation on how to use the rsync, rok, writable, and wsync properties for type narrowing against the State<RT> union.

Changes

Fix delayed state description

Corrected the A notation entry: async on initial load only, sync once resolved
Updated the delayed state section to show the two-phase lifecycle — await once, then get()/ok() work synchronously thereafter

Add type narrowing section

New section placed after the notation table explaining the four boolean discriminant properties:

Property	When `true`	Unlocks
`rsync`	Read is sync	`get()`
`rok`	Read never errors	`ok()`, result is `ResultOk<RT>`
`writable`	Accepts writes	`write()`
`wsync`	Write is sync	`write_sync()`

Checking these properties narrows the State<RT> union at both compile time and runtime — no casts needed:

function readValue<RT>(state: State<RT>) {
  if (state.rsync) {
    const result = state.get();           // safe: get() is present
    if (state.rok) return state.ok();     // safe: ok() is present, returns RT
    return result;                        // Result<RT, string>
  }
  return state.then(v => v);             // async path
}

async function writeValue<RT>(state: State<RT>, value: RT) {
  if (!state.writable) return;
  if (state.wsync) state.write_sync(value);
  else await state.write(value);
}

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

The readme incorrectly described delayed states as always-async, and lacked any documentation on how to use the `rsync`, `rok`, `writable`, and `wsync` properties for type narrowing against the `State<RT>` union. ## Changes ### Fix delayed state description - Corrected the `A` notation entry: async on initial load only, sync once resolved - Updated the delayed state section to show the two-phase lifecycle — `await` once, then `get()`/`ok()` work synchronously thereafter ### Add type narrowing section New section placed after the notation table explaining the four boolean discriminant properties: | Property | When `true` | Unlocks | |----------|-------------|---------| | `rsync` | Read is sync | `get()` | | `rok` | Read never errors | `ok()`, result is `ResultOk<RT>` | | `writable` | Accepts writes | `write()` | | `wsync` | Write is sync | `write_sync()` | Checking these properties narrows the `State<RT>` union at both compile time and runtime — no casts needed: ```ts function readValue<RT>(state: State<RT>) { if (state.rsync) { const result = state.get(); // safe: get() is present if (state.rok) return state.ok(); // safe: ok() is present, returns RT return result; // Result<RT, string> } return state.then(v => v); // async path } async function writeValue<RT>(state: State<RT>, value: RT) { if (!state.writable) return; if (state.wsync) state.write_sync(value); else await state.write(value); } ```  --- 📍 Connect Copilot coding agent with [Jira](https://gh.io/cca-jira-docs), [Azure Boards](https://gh.io/cca-azure-boards-docs) or [Linear](https://gh.io/cca-linear-docs) to delegate work to Copilot in one click without leaving your project management tool.

Chocolateandmilkwin (Migrated from github.com) reviewed

2026-03-17 15:15:35 +00:00