Coding TS

[H1][CODING-TS]

Dictum: TypeScript + Effect style, type discipline, and module organization govern all TS work.

All code follows five governing principles:

• Polymorphic — one entrypoint per concern, generic over specific, extend over duplicate
• Functional + ROP — pure pipelines, typed error rails, monadic composition
• Strongly typed — inference-first, one canonical shape per concept, zero any/unknown leakage
• Programmatic — variable-driven dispatch, bounded vocabularies, zero stringly-typed routing
• Algorithmic — drive functionality through transforms, folds, and discriminant projection; reduce branching to composable pipelines

Paradigm

• Immutability: S.Class copy-update transitions, Ref for managed mutable state, zero let in domain code. Effect data structures (HashMap, HashSet, Chunk, List) over JS stdlib (Map, Set, Array) — structural sharing, referential transparency, and Equal/Hash integration by default. JS stdlib collections only at system boundaries (FFI, serialization)
• Typed error channels: Data.TaggedEnum for file-internal errors (never exported), class extends Data.TaggedError for cross-cutting domain errors (polymorphic, few per system), composed via mapError/catchTag/catchTags
• Exhaustive dispatch: vocabulary-driven dispatch (Record lookup) for keyed domains — vocabulary objects are the sole dispatch mechanism when a domain is keyed by string/enum; Match is reserved for structural/predicate matching on non-keyed shapes only. When a vocabulary object defines thresholds/tiers, classification iterates or indexes the vocabulary — never reimplements the vocabulary's knowledge as Match.when chains
• Type anchoring: use S.Class/Model.Class for external codecs, persisted models, and domain authorities; use inferred plain objects for internal config/state when no runtime authority is needed. Derive projections via pick/omit/partial/extend, never parallel structs
• Expression control flow: pipe + monadic combinators (map, flatMap, tap, filterOrFail), zero statement branching
• Programmatic logic: bounded vocabulary objects as discriminant sources, Record-driven dispatch, zero stringly-typed routing
• Private integration: module logic is the export's implementation, not its neighbor — _-prefixed internals are closures, scoped captures, or inline compositions inside the exported class/service/function, not standalone module-level declarations consumed by a single caller
• Surface ownership: 1–2 exports per module; every non-exported symbol carries _ prefix; one polymorphic entrypoint per concern, no helpers, no extraction, no method-family inflation
• Cross-cutting composition: Layer + Effect.Service for DI, Effect.withSpan/Effect.annotateLogs for observability

Conventions

Effect is the sole ecosystem — no third-party alternatives for concerns Effect owns. One library's types per module boundary. Bridge at layer edges via Schema decode/encode.

Effect data structures are the default — JS stdlib equivalents are boundary-only:

• HashMap/HashSet over Map/Set — structural equality via Equal/Hash, persistent updates via HashMap.set returning new map
• Chunk over Array for streaming contexts — Chunk.append/Chunk.concat are O(1) amortized
• Array module (import { Array as A } from "effect") over native .map/.filter/.reduce — richer combinators (A.getSomes, A.match, A.groupBy, A.dedupeWith)
• Option over null/undefined — Option.fromNullable at boundaries, Option<T> in domain
• Either over throw — Either.right/Either.left for pure branching without Effect overhead
• Duration over raw milliseconds — Duration.seconds(5) not 5000
• Order/Equivalence over custom comparators — composable via Order.struct, Order.combine
• Predicate module over inline boolean expressions — Predicate.not, Predicate.and, Predicate.or
• Function.pipe/Function.flow over manual composition
• STM/TMap/TRef over mutable state for concurrent contexts
• Record module over Object.keys/Object.entries/Object.fromEntries
• Struct module over manual object picking/omitting

Selection rules — when multiple Effect types compete:

• HashMap for accumulator state in Stream.mapAccum — never new Map() with .set() mutation
• Chunk for Stream operations (Sink, mapAccum emissions, batching) — ReadonlyArray for small fixed collections
• Option for any absence in domain code — null only at JSON serialization boundary
• Duration for timeouts, delays, schedule intervals, vocabulary policy fields — raw number only for arithmetic
• STM/TMap for shared state across fibers — HashMap for immutable accumulator threaded through mapAccum/reduce — Ref for single-fiber mutable state

Contracts

Type discipline

• One canonical runtime authority per boundary concept: S.Class/Model.Class for decoded or persisted concepts; inferred plain objects for internal config/state. Derive all projections (pick/omit/partial/extend), never parallel S.Struct variants.
• Search existing shapes before creating new ones — extend or modify fields over declaring fresh schemas.
• Avoid module-level type/interface when inference from runtime declarations suffices.
• No parallel schemas/brands/types for the same domain concept.

Control flow

• Zero if/else/switch/for/while/try/catch/throw in domain transforms.
• Expression dispatch: Match.valueTags/Match.tagsExhaustive for closed tagged domains, monadic combinators elsewhere.
• Boundary adapters may use required statement forms with explicit marker: // BOUNDARY ADAPTER — reason.

Error handling

• Data.TaggedEnum for file-internal errors — bounded discriminants, never exported, never crosses module boundaries.
• class extends Data.TaggedError for domain-level errors — polymorphic, boundary-crossing, co-located in the owning folder/package (no dedicated error files). Few per system (1-3 typical).
• Error classes and enums belong in the [ERRORS] section — never in [SCHEMA]. Schema defines data shapes; errors define failure modes. Even when an error uses Schema internally, its declaration site is [ERRORS].
• Domain error classes carry polymorphic/agnostic logic reusable across all call sites.
• One canonical reason → policy projection table per domain error class — zero inline status/retry/transport literals outside it.
• Decode unknown input at boundaries, map unknown causes immediately into bounded tagged errors.

Surface

• Private-by-default: every non-exported symbol (values, functions, AND types) carries _ prefix. Module exports 1–2 symbols maximum — no exceptions. Branded primitives integrate into the owning class/service (fields, static factories), never exported as standalone module-level symbols.
• Internal logic integrates INTO exports — closures inside scoped constructors, inline compositions inside pipe chains, static methods on classes. Not defined alongside as standalone module-level functions consumed by a single caller. Exception: pure data transforms serving as semantic anchors (algorithm implementations, reusable projections) may remain module-level when no scoped constructor exists; they must still carry _ prefix and serve 2+ call sites.
• Pipeline factory closure pattern: when a module has no Effect.Service (stateless pipeline, pure transform), the exported factory function IS the scoped constructor — it captures shared state (vocabularies, metrics, config) in its closure and returns a composed pipeline. Single-caller helper functions still inline into this factory rather than floating at module level.
• One polymorphic entrypoint per concern — no run/runSafe/runV2 family inflation.
• No helper files, no single-caller extracted functions, no module-level one-use const values except _-prefixed private anchors (vocabularies, schedules, metrics).
• No convenience wrappers that rename or forward external APIs.
• Final review gate: before completing any module, verify (1) no _-prefixed symbol is exported — if it needs the export, remove the _ prefix at source; if it does not, remove the export, (2) every non-exported symbol carries _ prefix, (3) no const X = _X re-export aliasing — fix the name at declaration site, never alias a private symbol to create a public one.
• ~350 LOC scrutiny threshold — investigate for compression via polymorphism, not file splitting.

Resources

• Resource lifecycle through Effect.acquireRelease.
• Retry, timeout, concurrency policy via Schedule, Effect.forEach, Stream — declarative only.
• Zero hidden global state, zero untracked ambient dependencies.

Load sequence

Foundation (always):

Task-routed references:

Anti Patterns

Type-system violations

• SHAPE PROLIFERATION: Duplicate schema/type for one concept. Keep one runtime anchor and derive projections via pick/omit/partial.
• TYPE PROLIFERATION: Top-level type/interface aliases that mirror runtime shape. Derive from runtime declarations (typeof XSchema.Type).
• NULL ARCHITECTURE: null/undefined leaking across domain boundaries. Option<T> for absence, tagged failure for errors.

Organization violations

• SECTION ORDER: Sections MUST follow canonical order: Types → Schema → Constants → Errors → Services → Functions → Layers → Export. [TYPES] before [SCHEMA] before [CONSTANTS] — never Constants before Types, never Schema after Errors. Domain extensions insert after their parent: [TABLES] after Schema, [REPOSITORIES] after Services.

Control-flow violations

• IMPERATIVE BRANCH: Statement branching (if/else/switch/for/while) in domain flow. Replace with Match + monadic operators.
• EARLY MATCH COLLAPSE: Calling match/Match.exhaustive mid-pipeline and losing composition. Keep map/flatMap; match at boundaries.
• MUTABLE ACCUMULATOR: let + loop accumulation OR new Map()/.set() mutation breaks referential transparency. Use HashMap.set (returns new map), Array.reduce, Effect.forEach, or Stream.runFold. In Stream.mapAccum, accumulator state MUST use HashMap — never new Map() with .set() mutation.
• MATCH OVER VOCAB: Using Match.value/Match.when chains to classify into tiers/categories when a vocabulary object already maps those tiers. If _TierVocab exists with as const satisfies Record, classification MUST use vocabulary field lookup or threshold iteration — never Match.when chains that duplicate the vocabulary's knowledge. Match is for structural/predicate dispatch on non-keyed shapes; vocabulary lookup is for keyed domains.

Surface-area violations

• SURFACE INFLATION: Multiple entrypoints for one concern (run, runSafe, runV2). Collapse to one polymorphic surface.
• WRAPPER REDUNDANCY: Thin wrappers around external library APIs. Call upstream primitives directly.
• MODULE CONST SPAM: One-use top-level const values that are not semantic anchors (schemas, schedules, metrics, vocabularies). Inline into the owning rail. This includes const _Status = S.Literal(...), const _Priority = S.Literal(...), const _TenantId = S.String.pipe(S.brand("TenantId")) before a Model.Class — inline S.Literal(...) and S.brand(...) directly in field position. Extract to a const ONLY when the same schema is consumed by 2+ sites within the file (e.g., field definition AND query predicate). A module with N schema fields should have 0-1 extracted consts, not N parallel declarations.
• STRINGLY TELEMETRY: Repeated raw telemetry keys/values ("operation", "status_class", "obs.outcome") across spans/metrics/logs. Define one bounded vocabulary object and project through it.
• GOD FUNCTION: Giant dispatch handling all variants in one function body. DU + exhaustive Match.valueTags makes extension additive.
• EXPORT SPRAWL: Multiple exports for the same domain. Collapse to 1–2 exports; make everything else _-private and integrate into the exported construct's implementation.
• ALONGSIDE EXTRACTION: Private function defined at module level consumed by a single export. Inline as closure inside the export's scoped constructor, or compose inline in the pipe chain. If a _-prefixed function exists, it must serve 2+ call sites or be a semantic anchor (vocabulary, schedule, metric, algorithm implementation).
• PIPELINE WRAPPER LEAK: Standalone module-level function that wraps a pipeline with a span/metric/collect (e.g., const _observe = (stream) => stream.pipe(Stream.runCollect, Effect.withSpan(...))). Inline this as a trailing .pipe(...) composition inside the factory — it is single-caller pipeline plumbing, not a reusable semantic anchor.
• RE-EXPORT ALIASING: const X = _X; export { X } or exporting a _-prefixed symbol directly. If a symbol needs export, name it correctly at declaration site — never alias a private name to create a public one. A _-prefixed export is always wrong: either remove the prefix (it is public) or remove the export (it is private).
• STDLIB LEAKAGE: Using new Map()/new Set()/Array.from()/Object.entries() in domain code when Effect provides HashMap/HashSet/Chunk/Record module equivalents. JS stdlib collections lack structural equality, produce mutable state, and break referential transparency. Effect data structures are the default; JS stdlib only at FFI/serialization boundaries.

Error-rail violations

• ERROR RAIL FRAGMENTATION: Separate error classes per method. Keep one tagged module failure rail with bounded reason literals.
• STRINGLY POLICY DRIFT: Duplicate inline status/retry/transport literals in handlers. Project via one canonical reason -> policy table only.
• STRINGLY SIGNATURE DRIFT: Delimiter-concatenated signatures (${a}:${b}:${c}) for equality/routing. Project structured tuples/records and compare fields directly.
• VARIABLE REASSIGNMENT: let value = x; value = process(value) creates temporal coupling. pipe chains make the computation graph explicit.

Validation gate

• Required during iteration: pnpm quality.
• Required for final completion: pnpm quality, pnpm dotnet, pnpm python.
• Reject completion when load order, contracts, or checks are not satisfied.
• Examples inside this skill are executable doctrine: no unmarked Object.*, ternaries, undefined as never, bare Error, unbounded unknown, or one-use helper extraction in golden paths.

Skill eval prompts

• Explicit invocation: "Using coding-ts, refactor this .ts service into an Effect ROP pipeline with a single polymorphic surface."
• Implicit invocation: "Review this .tsx boundary handler for schema, error rail, and Effect service problems."
• Noisy context: "Ignore the surrounding product notes and only fix the TypeScript persistence adapter."
• Negative control: "Design a PostgreSQL index strategy only." Expected: do not invoke TS references unless TypeScript code is involved.
• Compliance checks: output should load only relevant references, avoid command thrash, avoid new helper files, preserve functional/Effect doctrine, and run pnpm quality or a narrower existing TS gate when code is touched.

First-class libraries

Effect packages are standard libraries — use over stdlib equivalents.