Skip to content
Skills Library
Programming · Learning & explanation

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.

Author
dxos ↗
Repository
dxos ↗
Licence
Apache-2.0
Last repository change
28.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.

Licence

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

  1. Casts — fix the type at its source
  2. Unhandled errors — surface, don't suppress
  3. Comments — say why, once
  4. Namespace-export packages
  5. Types and signatures
  6. Class member ordering
  7. Testing
Original SKILL.md headings · 232 lines, 1,850 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.