async-iterables/AGENTS.md

Controlled async iterable – push values in, and receive feedback with for-of.

# Repository Guidelines

## Project Structure & Module Organization

- `async-iterable.ts`: Main source module exporting `createAsyncIterable` (ESM, TypeScript).
- `index.test.ts`: Node test runner tests colocated at the repo root.
- `dist/`: Build output (generated by `npm run build`). Do not edit by hand.
- Config: `tsconfig.json` (strict, noEmit), `.prettierrc`, `.prettierignore`, `package.json`.

## Build, Test, and Development Commands

- `npm run types`: Type-check with `tsc` (no emit). Fails on type errors.
- `npm run build`: Transpile TS → JS with Sucrase into `dist/`.
- `npm run clean`: Remove `dist/`.
- `npm test`: Run tests via Node’s built-in runner (`node --test`).
  Example: `node --test index.test.ts` to run a single file.

## Coding Style & Naming Conventions

- Formatting: Prettier (tabs, no semicolons, trailing commas, width 110).
  Run `npm x prettier -w .` before pushing.
- TypeScript: ESM ("type":"module"), `target`/`lib` set to `esnext`, Node ≥ 20.
- Imports: TS extension allowed (see `allowImportingTsExtensions`). Prefer named exports.
- Filenames: module files kebab-case (e.g., `async-iterable.ts`); tests use `<name>.test.ts`.

## Testing Guidelines

- Framework: Node test runner (`import { test } from 'node:test'`) with `node:assert/strict`.
- Location: colocate tests at root as `*.test.ts` or next to the module.
- Scope: Favor small, deterministic tests. No strict coverage threshold currently.
- Run: `npm test` locally; ensure new features include corresponding tests.

## Commit & Pull Request Guidelines

- Commits: Use Conventional Commits (e.g., `feat: add yieldIterable support`, `fix: handle early return`).
- PRs: Include a clear description, linked issue (if any), reproduction/behavior notes, and tests.
- Checks: Ensure `npm run types`, `npm test`, and `npm run build` succeed.

## Security & Configuration Tips

- Runtime: Node ≥ 20 required; ESM only.
- Publish: `prepublishOnly` builds the package; avoid committing `dist/`.
- Avoid default exports and breaking API changes without a major version bump.