dxos-code-style
/dxos-code-style
DXOS TypeScript authoring conventions. Use when writing or refactoring code — namespace-export packages, internal module imports, class member ordering, options-bag types, function overloads, the no-cast rule, the no-suppressing-unhandled-errors rule, the comment rule (say why, once), and test structure.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
DXOS TypeScript authoring conventions. Use when writing or refactoring code — namespace-export packages, internal module imports, class member ordering, options-bag types, function overloads, the no-cast rule, the no-suppressing-unhandled-errors rule, the comment rule (say why, once), and test structure.
Original author description
DXOS TypeScript authoring conventions. Use when writing or refactoring code — namespace-export packages, internal module imports, class member ordering, options-bag types, function overloads, the no-cast rule, the no-suppressing-unhandled-errors rule, the comment rule (say why, once), and test structure.
How it works
- Casts — fix the type at its source
- Unhandled errors — surface, don't suppress
- Comments — say why, once
- Namespace-export packages
- Types and signatures
- Class member ordering
- Testing
SKILL.md preview
---
name: dxos-code-style
description: >-
DXOS TypeScript authoring conventions. Use when writing or refactoring code —
namespace-export packages, internal module imports, class member ordering,
options-bag types, function overloads, the no-cast rule, the
no-suppressing-unhandled-errors rule, the comment rule (say why, once), and
test structure.
---
# DXOS Code Style
Authoring conventions for the DXOS monorepo. The always-on subset lives in
`AGENTS.md`; this skill holds the detail. Use `@dxos/echo` as the reference
implementation for the namespace-export pattern.
## Casts — fix the type at its source
Do NOT cast to silence a build error; fix the type where it originates.
- "Cast" means `as T`, `as any`, `as unknown as T`, non-null `!`, or a widened /
`any` signature added to silence a type error. `as const` is NOT a cast — it
narrows a literal rather than bypassing the checker, and is always acceptable
(no comment or justification needed).
- Default: fix the type at its source (inference, signature, generic), not the
call site that surfaced the error. A red typecheck during a refactor is a
finding, not an obstacle to paper over.
- Casts are only acceptable at genuine type-system boundaries (external / untyped
data, deliberate coercions), and must carry a concise comment saying why no
typed alternative exists.
- **Before every commit/PR**, audit your diff for new casts:
`git diff origin/main | grep -nE '\bas (any|unknown|[A-Z])|as unknown as'`.
Justify or remove each; do not defer to review.
- Casts accumulate fastest during large codemods — treat each as a deliberate
decision, never an autopilot stopgap.
- Use @dxos/util `trim` to create multi-line strings (e.g., prompts).
## Unhandled errors — surface, don't suppress
Unhandled errors and rejections are findings; surface them and fix the root
cause. Do NOT silence them to make a suite go green.
- **Never set `dangerouslyIgnoreUnhandledErrors: true`** in any vitest config
(shared `vite.base.config.ts` or a per-package config). It lets a run exit 0
despite unhandled rejections, hiding real failures — including the teardown
races it is usually reached for. It has slipped in before; keep it out.
- A flaky teardown rejection (e.g. vitest worker rpc closing while a console log
is pending, browser/birpc close races) is a bug to fix at its source — close
the resource, await the pending work, or disable what leaks — not to blanket-
ignore. If a specific, understood signature must be tolerated, filter exactly
it via `onUnhandledError` (returning `false` only for that case) so every other
unhandled error stays fatal; never widen that to all errors.
- Same rule for a swallowed `unhandledRejection` handler, an empty `.catch()` on
real work, and a blanket try/catch that drops the error — handle or rethrow.
## Comments — say why, once
A comment earns its place by stating the _why_ the code can't — the constraint,
the non-obvious consequence, the reason a reader would otherwise "fix" it wrong.
The code already says _what_ it does; a comment that restates that is noise.
- **One load-bearing clause.** Not a multi-sentence essay. If you're explaining a
mechanism, state the constraint in a sentence and stop — resist narrating each
step, the alternatives you rejected, or how it used to work. This applies
hardest to JSDoc on a new abstraction, where the instinct to over-explain peaks.
- **Line-count is itself a signal.** If a comment runs past ~2 lines, that length
is almost never buying explanatory power proportional to its size — it's
restating what a competent reader already infers from the code, the variable
names, or the fact that it's test/fixture scaffolding. Compress to the one
clause a reader couldn't get any other way, or delete outright. A correct but
low-stakes "why" (this is a toolkit stub, this layer is a noop) does not
justify three sentences of scene-setting — the reader can see it's a stub.
- Test/fixture code gets a **lower** comment bar, not a higher one: "this is a
minimal/fake X for testing Y" is exactly what the surrounding `describe`
block, filename, and variable names (`TestToolkit`, `*LayerNoop`,
`scripted*`) already communicate — restating it in prose adds nothing.
- Never narrate history or the conversation ("previously X, now Y", "as
requested", "changed to…"). State the current invariant as if it always was.
- Delete a comment that a competent reader gets from the code itself. Prefer a
clearer name or signature over a comment that compensates for an unclear one.
- End with a period. JSDoc public functions.
- **Before every commit/PR**, audit the comments in your diff:
`git diff origin/main | grep -nE '^\+\s*(//|\*|/\*)'`. Re-read each added line
and cut it to its load-bearing clause — or delete it. A verbose comment is the
autopilot default; conciseness is the deliberate pass. Do not defer to review.
**A comment that survives your own audit deserves a second look** — try
deleting it first, and keep only words that don't come back on their own
from re-reading the code.
```ts
// ✅ why the code can't be the obvious thing, in one clause:
// Seeded across an identity change so the view refreshes in place, not to empty.
// ❌ restates the code / multi-sentence narration / history:
// Set displayItems to initialItems if it has items, otherwise the empty array.
// We used to reset here but that flashed empty, so now we hold the previous page
// and only replace it once the new query delivers its own results, which means…
// ❌ correct but over-explained test scaffolding — the name/context already says this:
// A minimal echo tool: the deterministic developer code the loop invokes when the
// (scripted) model emits a tool call. Its handler runs for real, so a genuine
// tool-call → result → continue cycle is exercised without any live model.
const TestToolkit = Toolkit.make(Tool.make('Echo', { ... }));
// ✅ same fact, one clause, or just delete it and let the name carry it:
// Real handler, so tool-call → result → continue is a genuine cycle, not a mock.
const TestToolkit = Toolkit.make(Tool.make('Echo', { ... }));
```
## Namespace-export packages
Packages are increasingly organized as namespace exports. Modules have
capital-case names and are re-exported as namespaces:
```text
src/
Foo.ts
Bar.ts
BazError.ts
index.ts
testing/
index.ts
internal/
foo.ts
bar.ts
baz.ts
```
```ts
// index.ts
export * as Foo from './Foo';
export * as Bar from './Bar';
export * as BazError from './BazError';
```
```ts
// Foo.ts
// @import-as-namespace
export const one = 1;
export const two = 2;
export const func: {
(a: string): number;
(a: number): string;
} = (a) => {
return a;
};
```
- The `@import-as-namespace` linter directive marks a file as a namespace export.
- Internal code is hidden in `internal/`, which is not exported.
- `testing/` is the exception (exported directly).
- Errors follow the `effect` package. An error that belongs to one namespace is exported from it
(`Operation.NoHandlerError`, like `Cause.TimeoutError`). A family of errors with no owning
namespace gets a `<Domain>Error` namespace module (`FunctionsAiError.UpstreamError`, like
`SqlError` or `HttpClientError`). There is no catch-all `errors` export.
- A namespace import uses the module's name. When the file already binds that name (another
package's namespace, a local declaration, or a global such as `Map` or `Error`), prefix it with
the package's short name: `ToolkitHooks` for `@dxos/app-toolkit/Hooks`, `GraphHooks` for
`@dxos/plugin-graph/Hooks`, `EchoError` for `@dxos/echo/Error`. app-framework's namespace keeps
the bare name. `import-as-namespace` enforces this for package subpaths.
- For a namespace file, avoid prefixing top-level types with the namespace name —
inside `Foo.ts` prefer `Manager`, `Service`, `Options` over `FooManager`,
`FooService`, `FooOptions` (callers see `Foo.Manager` either way).
### Internal module imports
For `@dxos/echo`-style entrypoints importing `src/internal/<Module>/`: import the
capitalized internal barrel as a lowercase `*Internal` namespace —
`import * as objInternal from './internal/Obj'`,
`import * as queryInternal from './internal/Query'`. Do not deep-import
submodules (`./internal/Obj/atoms`, `./internal/Ref/ref`, etc.); re-export needed
symbols from the module's `index.ts` instead. The top-level `./internal` barrel is
for cross-cutting re-exports only — prefer the per-module barrel when a single
entrypoint owns the dependency. Atom factories inside internal modules use the
`makeAtom` name (not `make`) to avoid clashing with public `make` APIs.
## Types and signatures
- Common suffix for constructor option-bag types is `Options` (e.g.
`SpawnOptions`, `ManagerImplOptions`) — pick this over `Opts` / `Props` /
`Config`.
- Keep React component Props types immediately before the component function.
- Take an options object when a constructor or function has more than a few
readonly props, especially when several are optional or share a logical group.
- For exported functions with multiple overloads, declare them as `const` with
the overload signatures inline in the type annotation rather than
`export function` with repeated declarations:
```ts
export const myFn: {
<T extends Foo>(a: T): Bar<T>;
(a: string): Bar<any>;
} = (a): Bar<unknown> => { ... };
```
## Class member ordering
Consider: static fields → public readonly → public mutable → private readonly
(incl. constructor-injected) → private mutable → constructor → public methods →
private methods. Within each group, rank properties roughly most-important to
least — "further up the stack" (closer to public API), required over optional,
readonly over mutable.
## Testing
- Place tests near modules as `module.test.ts`. Use vitest with `describe` /
`test` (not `it`); prefer `test('foo', ({ expect }) => ...)`.
- **Prefer extending existing test suites over creating new ones.** Look for a
suite that already covers the area before adding a file. A small number of
cohesive suites beats many fragmented ones.
- **Test at the level that is naturally the public API.** Exercise the seam
consumers actually use (exported surface, a service/manager's public methods),
not private internals. This keeps tests resilient to refactors and documents
real usage.
- Prefer a unified `TestLayer` for all tests rather than one per test.
`TestLayer(opts?)` can be parametrized so tests configure it.
- Place test layer, configuration, and main definitions at the top of the suite;
helpers at the bottom.
- **Never wrap an official API in a trivial local helper.** A one-liner like
`const makeBody = (text: string) => Obj.make(Body, { text })` renames the API
rather than removing duplication: the reader has to jump to the definition to
see what is under test, and several of them turn a suite into an ad-hoc DSL.
Inline the real call — `Obj.make(Body, { text: 'x' })` — so the API being
exercised stays visible next to the assertion. A helper earns its place only
when it composes several calls or encodes a non-obvious setup sequence.
- **Never sleep or poll for a result — await the concrete state.** A poll
(`expect.poll`, a retry loop, `await sleep(n)` before an assertion) hands the
test's control flow to a timer: it asserts whatever the system happened to
finish by an arbitrary deadline, so a real ordering bug degrades into a slow
pass and load degrades into a flake. Raising the timeout hides the problem
rather than fixing it. Wait on the event, promise or callback that **is** the
state being asserted — a `Trigger` woken by the write in question, a handle's
`whenReady`, the resolution of the call that does the work. When the subject
exposes no such signal (a fire-and-forget push, a best-effort send with no
ack), add the narrowest one — wrap the storage, transport or adapter it writes
through and await that — rather than sleeping past the gap. `TestClock` covers
time-dependent logic. Worked example: `withSaveSignal` in
`packages/core/echo/echo-host/src/automerge/automerge-subduction.test.ts`,
which awaits the receiving peer's own save because subduction's propagation
returns before delivery.
Versions
The database has no other skills named dxos-code-style.
Database snapshot: 13.11.2026 · package version 8abc1ecdc3a5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95dxos-operations
Guide for defining and implementing Operations in DXOS. Use when creating operation definitions, writing handlers, structuring operation modules, using OperationHandlerSet, or migrating from the old FunctionDefinition API. - 95dxos-echo
Guide for ECHO (DXOS object graph / local-first DB). Use when adding or changing queries, filters, schema types, Ref/DXN handling, Database service layers, EchoClient/space DB access, or React ECHO hooks. - 100ts-google
Google TypeScript style guide for writing clean, consistent, type-safe code. This skill should be used when writing, reviewing, or refactoring TypeScript code. Triggers on TypeScript files, type annotations, module imports, class design, and code style decisions. - 90google-ts-styleguide
Google TypeScript Style Guide reference for writing, reviewing, and refactoring TypeScript code. Use this skill whenever you are writing TypeScript code, reviewing TypeScript code, refactoring TypeScript, configuring ESLint or linter rules for TypeScript, or when the user asks… - 100typescript-write
Apply house coding standards to everyday application work. TRIGGER WHEN: writing or reviewing TypeScript/JavaScript code, including types, generics, async patterns, module boundaries, and style conventions. DO NOT TRIGGER WHEN: React performance (use react-development), or… - 100typescript-write
Apply house coding standards to everyday application work. TRIGGER WHEN: writing or reviewing TypeScript/JavaScript code, including types, generics, async patterns, module boundaries, and style conventions. DO NOT TRIGGER WHEN: React performance (use react-development), or…