SkillAgentSearch skills...

nw-fp-typescript

TypeScript language-specific patterns with fp-ts/Effect, discriminated unions, and railway-oriented error handling

Install / Use

npx skills add nWave-ai/nWave --skill nw-fp-typescript

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

87/100

Supported Platforms

Universal

Our assessment of nw-fp-typescript

nw-fp-typescript scores 87/100 on our quality scale, 2226th of 4,698 Development & Engineering skills we index (top 48%).

Its SKILL.md is 9.0 KB long, well organised into 21 sections with 13 code examples: a thorough specification that gives an agent plenty to work with.

It has 617 GitHub stars, a meaningful sign that others use it.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so nw-fp-typescript is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

nw-fp-typescript compared with similar skills

All 4 of these similar skills score higher than nw-fp-typescript; compare them before choosing.

SkillScoreStarsUpdatedFormat
nw-fp-typescript (this skill)by nWave-ai876172mo agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md

Frequently asked questions

How do I install nw-fp-typescript?
Run npx skills add nWave-ai/nWave --skill nw-fp-typescript. The install tabs above show the steps for each supported agent.
Which AI agents does nw-fp-typescript work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is nw-fp-typescript safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is nw-fp-typescript still maintained?
The repository was last updated about 2 months ago, so nw-fp-typescript is actively maintained.

name: nw-fp-typescript agent: nw-functional-software-crafter description: TypeScript language-specific patterns with fp-ts/Effect, discriminated unions, and railway-oriented error handling user-invocable: false disable-model-invocation: true

FP in TypeScript -- Functional Software Crafter Skill

Cross-references: fp-principles | fp-domain-modeling | pbt-typescript

When to Choose TypeScript

  • Best for: teams already on the Node/browser ecosystem wanting FP DISCIPLINE without a new runtime | full-stack projects sharing domain types between client and server | the most common first encounter with FP for many engineers
  • Not ideal for: teams wanting the compiler to ENFORCE purity (TS purity is a convention, any/as can always escape it) | CPU-bound work needing a stricter type system's exhaustiveness guarantees

[STARTER] Quick Setup

mkdir order-service && cd order-service && npm init -y
npm install typescript fp-ts --save
npm install --save-dev fast-check vitest
npx tsc --init --strict

Test runner: Vitest or Jest. "strict": true in tsconfig.json is load-bearing -- without it, null/ undefined silently widen every type and most patterns below lose their guarantee.

[STARTER] Type System for Domain Modeling

Choice Types (Discriminated Unions)

type PaymentMethod =
  | { readonly _tag: "CreditCard"; readonly cardNumber: string; readonly expiryDate: string }
  | { readonly _tag: "BankTransfer"; readonly accountNumber: string }
  | { readonly _tag: "Cash" };

The shared _tag field is the discriminant: a switch on _tag narrows the union per-branch, and with "strict": true a missing case is a compile error via the never exhaustiveness check below.

Record Types and Branded Domain Wrappers

interface Customer {
  readonly customerId: CustomerId;
  readonly customerName: CustomerName;
  readonly customerEmail: EmailAddress;
}

type OrderId = number & { readonly __brand: "OrderId" };
type EmailAddress = string & { readonly __brand: "EmailAddress" };

TypeScript has no true newtype -- a branded intersection type is the idiomatic substitute: OrderId is structurally a number at runtime (zero cost) but the __brand phantom field stops the compiler from accepting a bare number where an OrderId is expected.

[INTERMEDIATE] Smart Constructors

import { Either, left, right } from "fp-ts/Either";

function mkEmailAddress(raw: string): Either<ValidationError, EmailAddress> {
  return raw.includes("@")
    ? right(raw as EmailAddress)
    : left({ _tag: "InvalidEmail", raw });
}

The brand cast (as EmailAddress) happens ONLY inside the smart constructor -- callers never cast directly, so every EmailAddress in scope has passed mkEmailAddress.

[INTERMEDIATE] Composition Style

pipe for Left-to-Right Composition

import { pipe } from "fp-ts/function";
import * as E from "fp-ts/Either";

const placeOrder = (raw: RawOrder): Either<OrderError, Confirmation> =>
  pipe(raw, validateOrder, E.chain(priceOrder), E.chain(confirmOrder));

E.chain is Either's bind -- short-circuits on Left, threads the Right value forward.

Effect (the newer alternative to fp-ts)

import { Effect } from "effect";

const placeOrder = (raw: RawOrder): Effect.Effect<Confirmation, OrderError> =>
  Effect.gen(function* () {
    const validated = yield* validateOrder(raw);
    const priced = yield* priceOrder(validated);
    return yield* confirmOrder(priced);
  });

Generator-based Effect.gen reads imperatively while remaining a pure DESCRIPTION of the computation until Effect.runPromise/runSync actually executes it -- the same "build a value, run it at the edge" discipline Haskell's IO enforces at the type level.

Accumulating Validation Errors

import { validate } from "fp-ts/Apply";

const validateCustomer = (raw: RawCustomer) =>
  pipe(
    { name: validateName(raw.name), email: validateEmail(raw.email) },
    ({ name, email }) => E.Do.pipe(E.apS("name", name), E.apS("email", email)),
  );

apS/Applicative validation collects ALL failures via Either's Semigroup on the error side, unlike chain which stops at the first.

[INTERMEDIATE] Effect Management

Plain TypeScript has no purity enforcement -- Effect's own Effect<A, E, R> type is the closest analogue to Haskell's IO: a VALUE describing a computation, not the computation itself, so a function returning Effect<Order, never, never> is provably side-effect-free by its type alone (no ambient R requirement, no E to fail with) in a way a bare Order return never was.

// Pure domain logic -- ordinary function, no Effect wrapper needed
const calculateDiscount = (order: Order): Discount =>
  order.lines.length > 10 ? 0.1 : 0.0;

// Effectful boundary -- Effect<A, E, R> makes the DB dependency explicit in R
const saveOrder = (order: Order): Effect.Effect<void, DbError, OrderRepository> =>
  Effect.gen(function* () {
    const repo = yield* OrderRepository;
    yield* repo.save(order);
  });

[ADVANCED] Ports as Interfaces, Adapters as Layers (Hexagonal Architecture)

class OrderRepository extends Context.Tag("OrderRepository")<
  OrderRepository,
  { readonly findOrder: (id: OrderId) => Effect.Effect<Option<Order>>; readonly save: (o: Order) => Effect.Effect<void> }
>() {}

const PostgresOrderRepository = Layer.succeed(OrderRepository, {
  findOrder: (id) => Effect.tryPromise(() => db.query("SELECT * FROM orders WHERE id = $1", [id])),
  save: (order) => Effect.tryPromise(() => db.insert("orders", order)),
});

Context.Tag is the port; Layer provides the adapter. Tests substitute a Layer.succeed backed by an in-memory map, with no framework or DI container needed.

[INTERMEDIATE] Testing

Frameworks: fast-check (property-based, integrates with Vitest/Jest) | Vitest (fast, ESM-native) | Effect's own @effect/vitest for testing Effect values directly. See pbt-typescript for detailed PBT patterns.

Property Test Example

import fc from "fast-check";
import { test } from "vitest";

test("round-trips through serialization", () =>
  fc.assert(fc.property(orderArbitrary, (order) => deserialize(serialize(order)) === order)));

test("validated orders always have a positive total", () =>
  fc.assert(
    fc.property(rawOrderArbitrary, (raw) => {
      const result = validateOrder(raw);
      return E.isLeft(result) || result.right.total > 0;
    }),
  ));

Custom Arbitrary

const emailArbitrary: fc.Arbitrary<EmailAddress> = fc
  .tuple(fc.stringMatching(/^[a-z]{1,10}$/), fc.stringMatching(/^[a-z]{1,8}$/))
  .map(([user, domain]) => `${user}@${domain}.com` as EmailAddress);

[ADVANCED] Idiomatic Patterns

Exhaustiveness Checking via never

function describe(method: PaymentMethod): string {
  switch (method._tag) {
    case "CreditCard": return `Card ending ${method.cardNumber.slice(-4)}`;
    case "BankTransfer": return `Transfer from ${method.accountNumber}`;
    case "Cash": return "Cash";
    default: {
      const _exhaustive: never = method; // compile error if a case is missing
      return _exhaustive;
    }
  }
}

Option Instead of null/undefined

import { Option, some, none, fromNullable } from "fp-ts/Option";

const findCustomer = (id: CustomerId): Option<Customer> =>
  fromNullable(database.get(id));

Composes with map/chain the same way Either does, avoiding a null-check tree at every call site.

Maturity and Adoption

  • fp-ts is in low-maintenance mode: Effect is the actively developed successor (built by overlapping authors) and is where new projects should start; fp-ts remains fine for existing codebases.
  • Purity is a convention, not enforced: nothing stops a "pure" function from calling Date.now() or Math.random() inline; code review and the effect-typing discipline above are the only guard.
  • Effect's learning curve is steep: Effect<A, E, R>'s three type parameters and generator syntax take longer to internalize than fp-ts's Either/TaskEither alone; introduce incrementally.

Common Pitfalls

  1. as casts defeating brands: a branded type (OrderId) is only as strong as the discipline never to cast an arbitrary number into it outside the smart constructor.
  2. Mixing Promise and Effect/TaskEither: pick one effect representation per boundary; interop (Effect.tryPromise, TE.tryCatch) at the edge, never scattered through domain logic.
  3. interface merging surprises: TypeScript's structural typing means two unrelated interfaces with the same shape are interchangeable; branded types (above) are the fix, not a naming convention alone.
  4. Non-exhaustive switch without strict: the never exhaustiveness check in Idiomatic Patterns only fires under "strict": true; without it a missing case silently falls through.

Related Skills

View on GitHub
GitHub Stars617
CategoryDevelopment
Updated2mo ago
Forks63

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions