Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (54 loc) · 3.3 KB

AGENTS.md

File metadata and controls

72 lines (54 loc) · 3.3 KB
Raw

AGENTS.md

Guidance for coding agents working on the zeed repository. For end-user documentation see README.md.

Project

Zero-dependency TypeScript utility library for universal JavaScript (browser, Node, Deno, Bun).

  • Zero runtime dependencies
  • Strict TypeScript, full type inference
  • Tree-shakable ESM with CJS fallback
  • Platform split: src/browser/, src/node/, src/common/

Commands

Package manager: pnpm (>= 10). Node >= 20. nr is a binary from @antfu/ni that runs package.json scripts.

pnpm build            # tsdown build (ESM + CJS + types)
pnpm check            # tsc --noEmit
pnpm watch            # incremental build
pnpm test             # type check + vitest run (node + common)
pnpm coverage         # vitest with coverage
pnpm vitest run path/to/file.spec.ts   # single test file
pnpm test:chromium    # browser tests via playwright (also :firefox, :webkit)
pnpm test:browser     # browser tests with preview UI
pnpm lint             # eslint
pnpm lint:fix
pnpm build:docs       # typedoc -> docs/

Layout

src/
  common/   platform-agnostic (schema, msg, data, log core, ...)
  browser/  DOM, LocalStorage, browser log handler
  node/     fs, env, node log handler
  index.all.ts      universal entry
  index.browser.ts  browser build
  index.node.ts     node build
  index.jsr.ts      JSR registry entry

Conditional exports in package.json route consumers to the right build. Ignore _archive/, dist/, docs/, demos/.

Subsystems

  • common/schema/ - Standard Schema compatible runtime validation, exposed as z. z.object, z.string, z.stringLiterals, .parse, .optional, .default, z.infer. schema['~standard'] exposes the Standard Schema interface.
  • common/msg/ - Layered messaging: Emitter (typed events), Channel (postMessage abstraction), PubSub, Messages (RPC with Promise/timeout/retry), Encoder. See src/common/msg/README.md.
  • common/log/ + platform handlers - Logger('name'), levels info/warn/error. Env: ZEED=* or DEBUG=* (ZEED wins), ZEED_LEVEL=info, ZEED_LOG=/path/file.log. Handlers: LoggerConsoleHandler, LoggerBrowserHandler, LoggerNodeHandler, LoggerFileHandler.
  • common/data/ - arrayUnique, arrayShuffle, arrayGroupBy, camelCase, snakeCase, slugify, useBase(62), deepEqual, deepMerge, objectFilter, objectPluck, sortedItems (CRDT).

Conventions

  • 2-space indent, no tabs.
  • Strict TS. Explicit types only where inference is unclear.
  • Relative imports within a module, barrel imports across modules.
  • Tests live next to code: array.ts + array.spec.ts. Vitest globals enabled.
  • New utilities: aim for 100% coverage.
  • Browser-only code in src/browser/, node-only in src/node/, everything else in src/common/.
  • Each module has an index.ts barrel.

Build

  • Bundler: tsdown (rolldown-based). Config in tsdown.config.ts.
  • Output: dist/ with .mjs, .cjs, and .d.mts/.d.cts declarations per entry (e.g. dist/index.all.d.mts, dist/index.node.d.cts).
  • Features: tree-shaking, minification, source maps, code splitting.

Release

pnpm prep runs lint-fix, type check, full test suite, and doc upload. pnpm npm:release publishes to npm. pnpm build:docs generates typedoc into docs/ (published to https://zeed.holtwick.de/).