@zendrex/annotate

Typed Stage-3 decorators with scoped metadata reads. Zero dependencies, no reflect-metadata.

Annotate gives decorator authors one handle that creates the decorator and reads metadata back with the right type.

bun add @zendrex/annotate

Works with npm, pnpm, and yarn. Any toolchain that emits Stage-3 decorators can use it on Node, Bun, and modern browsers. Ships ESM, CJS, and TypeScript declarations.

Overview

• Annotate.class / method / field / accessor: typed decorators with built-in readers
• Collision-proof symbol keys per handle; optional label for diagnostics only
• Typed selectors: read(Class).get((instance) => instance.member) instead of string names
• cardinality: "one" (default) or "many" for repeatable decorators
• Annotate.intercept.*: method, accessor, and field interceptors with ctx.get(instance)
• Low-level reflect, prepare, mintUniqueKey, mintListKey for tooling that owns keys

Prerequisites

| Approach | Typical use | Requirements | | --- | --- | --- | | Runtime Symbol.metadata | Engines that already expose Symbol.metadata | TypeScript 5.2+, experimentalDecorators: false, Stage-3 decorator transform | | Shim | Node, Bun, older browsers, embedded runtimes, or any engine without Symbol.metadata | Import @zendrex/annotate/shim once before decorated classes load |

TypeScript must use Stage-3 decorators (experimentalDecorators: false). Legacy TypeScript decorators and parameter decorators are not supported.

Quick start

import { Annotate } from "@zendrex/annotate";

const Route = Annotate.method((method: "GET" | "POST", path: string) => ({ method, path }));

class Users {
  @Route("GET", "/")
  list() {}
}

Route.read(Users).get((users) => users.list);
// { method: "GET", path: "/" }

Route.read(Users).methods();
// [{ kind: "method", name: "list", static: false, metadata: { method: "GET", path: "/" } }]

Examples

Builders

Direct metadata:

const Controller = Annotate.class<string>();
const Column = Annotate.field<{ type: "text" | "int" }>();

Argument mapper:

const Route = Annotate.method((method: "GET" | "POST", path: string) => ({ method, path }));

Options (label, validation, host restriction):

class ControllerBase {}

const Route = Annotate.method({
  label: "Route",
  args: (method: "GET" | "POST", path: string) => ({ method, path }),
  validate: (route) => {
    if (!route.path.startsWith("/")) {
      throw new Error("path must start with /");
    }
  },
  requires: ControllerBase,
});

Available builders:

Annotate.class(...)
Annotate.method(...)
Annotate.field(...)
Annotate.accessor(...)

Reading

Class annotations — no selector:

const Controller = Annotate.class<string>();

@Controller("users")
class Users {}

Controller.read(Users).get(); // string | undefined

Member annotations — typed selectors:

Route.read(Users).get((users) => users.list);
Route.read(Users).static.get((ctor) => ctor.health);

Selectors must synchronously read exactly one public member. Calling a method, reading none, or reading multiple members throws InvalidSelectorError.

Collection helpers return inherited metadata most-derived-first:

Route.read(Users).entries();
Route.read(Users).methods();
Column.read(Users).fields();
Watched.read(Users).accessors();

Entries include kind, name, static, and metadata:

const staticRoutes = Route.read(Users)
  .methods()
  .filter((route) => route.static);

Cardinality

Default is one value per decoration site:

const Role = Annotate.method<string>();
Role.read(Users).get((users) => users.list); // string | undefined

Repeatable decorators:

const Tag = Annotate.method<string>({ cardinality: "many" });

class Api {
  @Tag("public")
  @Tag("internal")
  list() {}
}

Tag.read(Api).get((api) => api.list); // readonly string[]

Stage-3 decorators apply inner-first, so the example above reads ["internal", "public"].

Interceptors

Under Annotate.intercept:

const Log = Annotate.intercept.method<string>({
  label: "Log",
  wrap: (original, ctx) =>
    function (this: object, ...args: unknown[]) {
      console.log(ctx.name, ctx.get(this));
      return original.apply(this, args as never);
    },
});

Hooks:

Annotate.intercept.method({ wrap: (original, ctx) => original });
Annotate.intercept.accessor({ get: (original, ctx) => original, set: (original, ctx) => original });
Annotate.intercept.field({ init: (initial, ctx) => initial });

ctx.get(instance) reads this interceptor's metadata on the current member. Return type follows cardinality: T | undefined for "one", readonly T[] for "many".

Low-level reflection

The high-level API does not expose metadata keys. For tooling that deliberately manages keys:

import { mintListKey, reflect } from "@zendrex/annotate";

const Tags = mintListKey<string>("tags");
reflect(Users).methods(Tags);

Also exported: prepare, createScopedReflector, and mintUniqueKey. Most applications should prefer Annotate.*.read(...).

Design notes

Keys. Each Annotate.* handle mints an internal symbol key. String label values are diagnostics only, not identity.

Storage. Metadata uses TC39 Symbol.metadata (Stage-3). The shim aligns Symbol.for("Symbol.metadata") with the transformer on engines without native support.

Readers. read(target) prepares the class, walks the prototype chain, and returns scoped readers. Member reads use proxy selectors so names stay type-checked.

Cardinality. "one" maps to a unique key; "many" maps to a list key. Duplicate one-cardinality decoration on the same site throws DuplicateMetadataError.

Validation. Optional validate hooks receive mapped metadata and a ValidateContext. Class and static-member checks run during decoration initialization; instance-member checks run when metadata is prepared, usually on first read or first instance creation. Failures become ValidationError. requires rejects hosts that do not extend the given base class.

Package exports

| Import | Provides | | --- | --- | | @zendrex/annotate | Annotate, errors, reflect, prepare, createScopedReflector, key minting, public types | | @zendrex/annotate/shim | Side-effect install of Symbol.metadata on older runtimes |

API reference

Builders

Annotate.class<TMeta>();
Annotate.class<TMeta>({ cardinality: "many" });
Annotate.class((...args) => meta);
Annotate.class({ label, args, validate, requires, cardinality });

Annotate.method / Annotate.field / Annotate.accessor — same shapes

Each builder returns a decorator function with .read(target).

Readers

Class:

Controller.read(Users).get();      // TMeta | undefined (or readonly TMeta[] if many)
Controller.read(Users).entries();    // ClassAnnotationEntry[]

Member:

Route.read(Users).get((users) => users.list);
Route.read(Users).static.get((ctor) => ctor.health);

Route.read(Users).entries();
Route.read(Users).methods();   // kind === "method"
Column.read(Users).fields();   // kind === "field"
Watched.read(Users).accessors(); // kind === "accessor"

Interceptors

Annotate.intercept.method({ label, wrap, validate, requires, cardinality });
Annotate.intercept.accessor({ label, get, set, validate, requires, cardinality });
Annotate.intercept.field({ label, init, validate, requires, cardinality });

PublicInterceptorContext: kind, name, static, get(instance).

Low-level

prepare(ctor);
reflect(target).class(key);
reflect(target).methods(key);
reflect(target).properties(key);
reflect(target).all(key);

createScopedReflector(ctor, key);
mintUniqueKey<T>(label?);
mintListKey<T>(label?);

Errors

All extend AnnotateError with a stable code:

| Class | Code | When | | --- | --- | --- | | DuplicateMetadataError | "duplicate" | one-cardinality annotation applied twice to the same site | | InvalidDecorationTargetError | "invalidTarget" | requires rejects the host class | | InvalidSelectorError | "invalidSelector" | selector does not read exactly one public member | | MissingMetadataError | "missing" | low-level throw-on-missing read found nothing | | UnregisteredClassError | "unregistered" | low-level reflect() query sees no registered metadata | | UnregisteredMetadataKeyError | "unregisteredKey" | low-level store receives an unregistered symbol key | | ValidationError | "validation" | a validate hook threw |

Runtime issues addressed

Annotate does not patch the engine. It stores metadata in annotate-owned structures and controls when decorations are flushed so reads stay correct on imperfect Stage-3 implementations.

| Issue | Typical runtimes | What Annotate does | | --- | --- | --- | | Symbol.metadata missing | Node, Bun, older browsers, some embedded engines | Import @zendrex/annotate/shim once so the transformer and runtime agree on Symbol.for("Symbol.metadata"). Native Symbol.metadata is left untouched when already present. | | Instance members register only after an instance exists | All Stage-3 engines | Instance-member decorations are queued and flushed on first prepare(ctor), first instance creation (via addInitializer), or first read that materializes the class. Call prepare(Users) to eager-flush without constructing. | | Shared instance addInitializer callbacks | Bun 1.3.13 (and similar) | Bun can reuse one initializer across classes so only the last registration runs. Annotate’s initializer only calls prepare(this.constructor), so whichever callback runs drains the correct class’s pending metadata. | | Skipped field value-replacement initializers | Bun 1.3 (var _init transformer bug) | When several fields in one class use Annotate.intercept.field, Bun may skip per-field initializer closures. Field interceptors keep a per-class index and can re-apply every field hook from the instance in one pass so each field still gets its own metadata. |

Regression tests for the Bun cases live under tests/integration/cross-class-isolation.test.ts and tests/integration/bun-multi-field.test.ts.

Import the shim once before decorated classes load on runtimes without native Symbol.metadata:

import "@zendrex/annotate/shim";

License

MIT