DEV Community: Martin Persson

Building Reliable AI Agents with TypeScript and Effect.ts

Martin Persson — Sat, 14 Nov 2026 19:41:54 +0000

AI agents are easy to prototype. Making them reliable enough for real engineering workflows is a different problem.

The Agent Is the Easy Part

I've spent quite a bit of time working with AI-assisted development lately. One thing I've noticed is how quickly you can put together an impressive demo. Give a model a few tools, ask it to perform a task, and suddenly you have an agent that appears to understand your entire workflow.

But connecting an LLM to an API isn't the difficult part. The difficult part is deciding what happens when that API is unavailable, the response doesn't match your expectations, or the agent makes an incorrect assumption.

I work primarily with TypeScript and have used Effect.ts extensively for building backends. That got me thinking: what if we treated an agent's tools like ordinary production services, with explicit dependencies, validated data, and predictable failures?

Let's build a small example.

What We're Building

Imagine an internal assistant that helps developers plan work from engineering tickets. You ask it to prepare a plan for ENG-142. It should retrieve the ticket, read the relevant engineering guidelines, and return a proposed implementation plan with tests and open questions.

It should not modify the codebase, update tickets, or deploy anything. This is a planning assistant, so read-only tools are enough.

We'll use three pieces:

Effect.ts for services, typed errors, dependency injection, and validation.
Zod and the AI SDK to describe the tool interface exposed to the model.
A small context service to provide knowledge about how our team builds software.

The AI SDK handles model interaction and tool calling. Effect handles the engineering work behind the tools.

1. Don't Trust External Data

Let's start with the ticket. Even if we trust our project-management system, its API response is still external data. We should validate it before the rest of our application relies on it.

import { Schema } from "effect";

const Ticket = Schema.Struct({
  id: Schema.String,
  title: Schema.String,
  description: Schema.String,
  area: Schema.Literal("backend", "frontend"),
});

type Ticket = typeof Ticket.Type;

Now the rest of the application can work with a known shape instead of passing arbitrary JSON into a prompt.

In a real integration, I'd also validate identifiers, normalize optional fields, and decide what the agent is allowed to see. More data isn't automatically better context, especially when privacy and compliance matter.

2. Model Failures Instead of Hiding Them

Now we need a service that retrieves a ticket. Effect makes it possible to express the failure modes in the type signature.

import { Context, Data, Effect } from "effect";

class TicketNotFound extends Data.TaggedError("TicketNotFound")<{
  id: string;
}> {}

class InvalidTicket extends Data.TaggedError("InvalidTicket")<{
  id: string;
}> {}

class TicketService extends Context.Tag("TicketService")<
  TicketService,
  {
    get: (
      id: string,
    ) => Effect.Effect<Ticket, TicketNotFound | InvalidTicket>;
  }
>() {}

This is one of the things I like most about Effect. The function doesn't just promise a Ticket. It also tells us which failures we expect to handle.

The implementation can call ClickUp, GitHub, or an internal API. The agent doesn't need to know which one. It only depends on the service contract.

That also makes the system easier to test. We can replace the real adapter with a fake one and verify the workflow without making network requests or spending tokens.

3. Context Is Part of the System

A ticket rarely contains enough information to produce a useful implementation plan. An agent needs to understand the conventions and constraints of the codebase.

For a backend task, that might include how we validate requests, where business logic belongs, and how authorization is enforced. For a frontend task, it might include our design system and testing conventions.

I'd rather make that knowledge available through a service than paste it into every new conversation.

class ContextService extends Context.Tag("ContextService")<
  ContextService,
  {
    forArea: (area: Ticket["area"]) => Effect.Effect<string>;
  }
>() {}

const loadPlanningContext = (id: string) =>
  Effect.gen(function* () {
    const tickets = yield* TicketService;
    const context = yield* ContextService;

    const ticket = yield* tickets.get(id);
    const guidelines = yield* context.forArea(ticket.area);

    return { ticket, guidelines };
  });

Here, ContextService is intentionally simple. In a larger system it could resolve relevant Markdown documentation, architectural decisions, or domain-specific instructions. The important part is that context retrieval becomes a deliberate, testable capability.

An LLM already knows TypeScript. It doesn't know why your team has chosen a particular way of writing TypeScript.

4. Expose a Small, Typed Tool

With those services in place, we can give the agent one tool: readTicketContext.

import { generateText, stepCountIs, tool } from "ai";
import { Effect } from "effect";
import { z } from "zod";

const result = await generateText({
  model: process.env.AI_MODEL!,
  system: `You are a planning assistant.
    Read the ticket context before writing a plan.
    Propose implementation steps, tests, and unknowns.
    Never claim that code was changed or tested.`,
  prompt: "Prepare an implementation plan for ENG-142.",
  stopWhen: stepCountIs(3),
  tools: {
    readTicketContext: tool({
      description: "Read a ticket and its engineering guidelines",
      inputSchema: z.object({
        id: z.string().regex(/^ENG-\d+$/),
      }),
      execute: async ({ id }) =>
        Effect.runPromise(
          loadPlanningContext(id).pipe(
            Effect.map((data) => ({ ok: true as const, data })),
            Effect.catchTags({
              TicketNotFound: () =>
                Effect.succeed({ ok: false as const, error: "Not found" }),
              InvalidTicket: () =>
                Effect.succeed({ ok: false as const, error: "Invalid ticket" }),
            }),
            Effect.provide(AppLayer),
          ),
        ),
    }),
  },
});

console.log(result.text);

AppLayer is where we provide the concrete implementations of TicketService and ContextService. It might connect to a real API in production and use in-memory data in tests. The code above focuses on the tool boundary, not the adapter setup.

Notice what we're not exposing: arbitrary HTTP requests, shell access, database queries, or tools that mutate tickets. The model can ask for approved context, and the application controls what actually happens.

We're also returning an explicit result when a ticket cannot be loaded. That lets the agent explain the problem instead of quietly making up missing requirements.

5. Test the Deterministic Parts

I wouldn't start by writing tests that ask an LLM to produce the exact same paragraph every time. I'd start with the parts that should behave predictably.

Can we decode the ticket response? Do we return the correct error for a missing ticket? Are backend guidelines selected for a backend ticket? Does the tool prevent unauthorized actions?

Those tests don't need a model. They need controlled services and clear expectations. We can test model behavior separately with representative scenarios and evaluate whether the generated plans are useful.

This separation matters. When something goes wrong, I want to know whether the issue came from the model, our context, an API integration, or a bug in the application.

Where Effect Actually Helps

Could you build this with plain TypeScript, Zod, and try/catch? Absolutely. For a small prototype, that's probably what I'd do.

Effect starts becoming interesting when the system grows: several external APIs, transient failures, retries, timeouts, tracing, shared dependencies, and workflows that need to remain testable. Those are familiar backend problems, even when an LLM happens to be involved.

It doesn't make the model deterministic. It helps make everything surrounding the model more explicit and predictable.

That's the part I care about.

From Agent Demos to Software Factories

In the earlier articles in my Software Factory Era series, I wrote about moving from AI-assisted coding toward engineering environments where agents can carry out larger parts of the development process.

This is a small example of what that foundation can look like. A single tool, a few services, explicit boundaries, and context that belongs to the team rather than to one developer's chat history.

We can expand it later with additional tools, approval workflows, better context retrieval, and automated verification. But I think the right starting point is to build one reliable capability and understand its limits before adding more autonomy.

The model is the unpredictable part. Everything around it should be engineered accordingly.

Stop Prompting AI. Start Engineering the Harness.

Martin Persson — Tue, 10 Nov 2026 14:27:45 +0000

Building the foundation for AI-native software engineering.

Your AI Doesn't Know Your Codebase

After spending a considerable amount of time working with AI in software development, I've noticed a recurring problem. AI is incredibly capable of writing code, but it often struggles to understand how an organization actually builds software.

It might know TypeScript, React, PostgreSQL, and countless architectural patterns, but it doesn't know why your team made a particular architectural decision six months ago. It doesn't understand which parts of your system are fragile, which business rules are critical, or why certain conventions exist.

Sometimes it doesn't even read the files it should have read before making changes.

As developers, we compensate by providing context, explaining architectural decisions, and correcting assumptions. Unfortunately, we often end up repeating this process across different conversations, tasks, and team members.

This raises an important question: why are we spending so much time teaching AI things our organization already knows?

Context Is Infrastructure

Most developers interact with AI through conversations. We describe a task, provide some context, review the result, and correct whatever the model misunderstood. This works reasonably well for individual tasks, but becomes increasingly inefficient when applied across an engineering organization.

Two developers using the same AI model can get significantly different results simply because they provided different context. One might get an implementation that follows the existing architecture, while another receives something that technically works but introduces entirely new patterns.

The problem isn't necessarily the model. It's the environment in which the model operates.

I believe we should start treating context as engineering infrastructure. Something that is deliberately designed, documented, versioned, and maintained rather than manually recreated in every conversation.

This doesn't mean feeding every document and source file into an enormous context window. It means organizing knowledge so that AI can find the right information when it needs it.

1. Make Your Architecture Understandable

One of the first things we've realized is that having access to the codebase isn't enough. AI can explore source code, but understanding a complex system requires more than reading individual implementations.

Consider authentication, for example. An agent might successfully identify the authentication middleware and understand how a request is validated. But that doesn't necessarily explain why certain endpoints require additional authorization, how permissions relate to business rules, or which architectural constraints should apply to new implementations.

We need documentation that captures this knowledge explicitly.

Not enormous documents describing every detail of the application, but focused Markdown files explaining important architectural decisions, business concepts, and established conventions.

For example:

docs/
├── architecture.md
├── authentication.md
├── domain.md
├── integrations.md
└── testing.md

These documents should explain responsibilities, boundaries, important decisions, and common pitfalls. They should also be maintained alongside the code, preferably as part of the normal development process.

The purpose isn't to prevent AI from exploring the codebase. It's to give it a reliable starting point and reduce the amount of unnecessary exploration required for every task.

Source code describes how a system is implemented. Good documentation provides the context needed to understand why it was implemented that way.

2. Turn Repeated Instructions Into Skills

Another problem becomes obvious when AI is used regularly across a team: developers repeatedly provide similar instructions.

How should an API endpoint be implemented? Which architectural conventions apply? How do we write integration tests? What should happen when an external service fails?

These are questions that an engineering team has often already answered.

We've invested quite heavily in shared AI instructions and specialized skills, including maintaining a separate repository for them. The idea is to make our engineering knowledge reusable rather than depending on individual developers remembering which instructions to include.

A skill can describe how to approach a particular type of task, which documentation to consult, which tools to use, and how to verify the result.

For example, a skill for implementing an API endpoint might instruct an agent to inspect existing routes, follow established patterns, use the appropriate validation utilities, and run relevant tests before considering the task complete.

The important part is that this knowledge becomes shared and maintainable.

When we discover a better approach, we update the skill. When architectural conventions change, we update the relevant instructions.

This is much more sustainable than having different developers maintain their own collections of prompts that gradually become inconsistent.

3. Give AI Tools, Not Just Instructions

Instructions and documentation provide knowledge, but an effective harness also needs capabilities.

There's a significant difference between explaining how to perform a task and providing the tools necessary to perform it.

Consider an agent implementing a ticket from a project-management system. Without an integration, a developer might need to copy the requirements into the conversation, locate relevant documentation, and manually supply additional context.

With the right tools, the agent could retrieve the ticket through an API, identify relevant documentation, load the appropriate skills, and inspect the affected parts of the codebase.

It could then implement the changes, run tests, and collect the results for review.

This doesn't necessarily require a complicated agent framework. In many cases, a well-designed script with a predictable interface is sufficient. The important thing is that the agent has access to reliable, reusable capabilities rather than depending on manual interaction.

We're currently taking this idea further by developing our own internal AI harness application. It's still under development, but the ambition is to bring shared knowledge, specialized capabilities, and engineering workflows together into a consistent environment.

The long-term goal is to reduce the amount of manual coordination required from developers while maintaining control over how work is performed.

4. Build Security and Compliance Into the Architecture

An AI harness also introduces responsibilities that go beyond developer productivity.

In our case, working in an environment with GDPR requirements means we need to think carefully about which information agents can access, how that information is processed, and which external services are involved.

An agent capable of retrieving documentation or interacting with internal systems should not automatically have unrestricted access to everything.

We need to consider authentication, authorization, data minimization, access boundaries, auditability, and appropriate human approval mechanisms.

For example, an agent working on an integration might need access to technical API documentation and test fixtures, but should not require access to real patient information or production credentials.

These concerns shouldn't be handled exclusively through instructions telling the model to behave responsibly. They need to be enforced through the tools and infrastructure surrounding it.

As we give agents more autonomy, the quality of these controls becomes increasingly important. The objective is to enable useful automation without compromising the security and privacy requirements of the organization.

5. Treat the Harness as an Internal Product

One of the most important lessons I've taken from this work is that an AI harness shouldn't be treated as a collection of configuration files that someone creates once and forgets.

It's an internal engineering product that requires ownership, maintenance, and continuous improvement.

When an agent repeatedly makes the same mistake, we should investigate why. Perhaps documentation is missing, an instruction is ambiguous, or a tool doesn't provide enough information. Sometimes the solution is a better test or an additional validation step.

Rather than correcting the same problem in individual conversations, we can improve the shared environment.

Over time, those improvements benefit everyone using the system.

This also creates an opportunity to evaluate how effective our AI workflows actually are. Are agents following architectural conventions? How often do implementations require manual corrections? Which tasks consistently fail? Where are developers still spending time providing missing context?

Answering these questions gives us a way to improve the harness based on evidence rather than assumptions.

Building the Foundation for Software Factories

In my previous article, Stop Writing Software. Start Building Software Factories, I explored the idea that software engineering is moving toward environments where specialized AI agents handle increasingly large parts of the development process.

I believe building a reliable AI harness is one of the most important steps toward that future.

Before we can expect multiple agents to collaborate autonomously, we need to give them a shared understanding of our systems, reliable tools, clear responsibilities, and mechanisms for verifying their work.

Some of these capabilities are already practical today. Others, particularly more autonomous workflows, still require experimentation and careful engineering.

We don't need to wait for the next generation of AI models to begin. We can improve our documentation, introduce reusable skills, connect existing tools, and establish appropriate security boundaries with the technology we already have.

As these foundations mature, we can gradually automate more of the development process without losing visibility or control.

I believe the future of AI-powered software engineering will depend not only on increasingly capable models, but also on the quality of the environments we build around them.

And for engineering teams, that's something we can start working on today.

Stop Writing Software. Start Building Software Factories

Martin Persson — Mon, 09 Nov 2026 15:50:51 +0000

The future of software engineering isn't about writing code faster. It's about building the systems that build software.

Let's Talk About Henry Ford

Before talking about AI, let's go back more than a hundred years and talk about Henry Ford.

Yes, Henry Ford. Bear with me.

In the early days of the automobile industry, cars were largely built by hand. Skilled workers assembled components piece by piece, making production expensive, slow, and difficult to scale.

Ford didn't invent the automobile or the assembly line. But he helped revolutionize manufacturing by introducing the moving assembly line into automobile production. Instead of relying on craftsmen building individual vehicles, he helped create a system capable of producing cars efficiently at scale.

His breakthrough wasn't a better car. It was a better way to build cars.

Of course, handcrafted cars still exist. Rolls-Royce is famous for its craftsmanship, and that's perfectly fine. If you can spend years building a single piece of software and sell it for millions, lucky you, I guess.

But for the rest of us, I think it's time to start building factories.

We've Been Building Cars by Hand for 60 Years

From punch cards and assembly languages to modern frameworks, cloud infrastructure, and automated deployments, software development has evolved enormously. We've become more efficient at nearly every step of the development process.

But fundamentally, developers have always been responsible for producing the software. We understand requirements, design solutions, write code, test it, and ship it. The tools have changed dramatically, but we're still building the car by hand.

AI changes that.

For the first time, we're approaching a world where developers don't necessarily have to implement the software themselves. Instead, we can design environments where AI agents perform much of the implementation, testing, and verification.

We're moving from building software to building systems that build software.

And that's a much bigger revolution than autocomplete on steroids.

I Love Writing Code. That's Becoming a Problem.

I genuinely love programming.

Sometimes I wish I could spend eight hours doing nothing but writing code. Line by line, solving problems, refactoring, and making everything beautiful. At the end of the day, I'd look at what I'd built and feel proud.

But how do I justify it?

Imagine telling my boss:

"Look at this feature! I spent eight hours writing it, and I'm really happy with the code."

And the obvious question would be:

"Why didn't you use AI? Couldn't you have done it in a fraction of the time?"

Honestly, that's a reasonable question. AI doesn't magically solve every problem in ten minutes, but spending hours manually implementing something that AI could help deliver much faster is becoming increasingly difficult to justify.

I didn't become a developer because I wanted to supervise automated systems. I became a developer because I love building things. But the more I work with AI, the more I realize that the most effective way to build something doesn't necessarily involve writing every line of code myself.

My job isn't simply to write code. My job is to solve problems.

That's a distinction I think many developers will have to confront.

An AI Coding Assistant Is Not a Software Factory

Right now, many developers use AI as a faster pair of hands. We describe a task, AI writes some code, we review it, make adjustments, and move on to the next task.

That's useful, but we're still driving every step of the process.

A Software Factory is something fundamentally different. It's an engineering environment where specialized AI agents have the instructions, tools, permissions, and feedback loops necessary to perform development work autonomously.

Instead of manually prompting an agent to implement a ticket, we design a system that can retrieve the ticket, understand the requirements, implement the changes, run the necessary tests, and prepare the result for release.

Humans still define objectives, architectural constraints, and approval boundaries. But the factory handles much of the execution.

The difference isn't how good the AI is at writing code. It's who is driving the process.

So, How Do We Build One?

Building a Software Factory doesn't mean throwing ten AI agents into a repository and hoping for the best. We need to engineer the environment around them, just as carefully as we would any other production system.

1. Give AI the right environment

Start with architecture, coding standards, documentation, and reusable instructions. Expose the tools your team already uses through scripts, APIs, and integrations.

AI should be able to read tickets, understand the codebase, run tests, inspect failures, and interact with your development workflow without requiring a developer to manually provide everything.

I've been experimenting with AI skills, reusable instructions, and ways to connect agents to project-management tools. One thing has become increasingly clear: the environment matters just as much as the model.

A powerful agent with insufficient context, unreliable tools, or no understanding of your architecture can introduce problems faster than a developer can fix them.

2. Build specialized agents

Imagine an engineering team consisting of specialized AI agents, each responsible for a particular part of the development process.

A Frontend Agent understands your UI components and design system. A Backend Agent understands your APIs, database, and business logic. An Architect Agent evaluates technical decisions and architectural consistency, while a QA Agent validates implementations and identifies potential problems.

Each agent has its own responsibilities, tools, and boundaries. They don't need to know everything about the entire application, but they need access to the knowledge and capabilities relevant to their work.

The important part isn't simply assigning different names to different agents. It's designing how they operate, what they're allowed to do, and how their work is verified.

3. Connect them into a production system

Now imagine a product manager creates a feature request.

An agent analyzes the requirements and breaks them into technical tasks. The Architect Agent evaluates the implementation approach, while the Frontend and Backend Agents handle their respective parts of the application.

Once the implementation is ready, the QA Agent runs tests and validates the result. If something fails, the relevant agent receives feedback, investigates the problem, and attempts to fix it.

This process continues until the implementation meets the required standards. The factory then prepares a pull request containing the changes, test results, and relevant technical decisions.

A human reviews important decisions and approves the release.

That's the factory: not an individual agent writing code, but a coordinated system capable of producing software through a repeatable engineering process.

4. Build quality control into the factory

AI can produce bad software incredibly quickly. Without proper controls, we're not building an effective Software Factory. We're simply automating the production of poor-quality software.

Tests, architectural rules, security checks, and observability need to be fundamental parts of the system. The factory must be able to verify that an implementation works, follows established conventions, and actually addresses the original requirements.

When something goes wrong, we need to understand what happened and why. And when an agent repeatedly makes the same mistake, we should improve the system rather than continuously correcting individual implementations.

The goal isn't to remove humans from every decision. It's to make human intervention increasingly focused on situations where our judgment provides the greatest value.

Developers Won't Disappear. Their Responsibilities Will Change.

When generative AI first appeared, people immediately started predicting the end of software developers. The argument was simple: if AI can write code, companies will need fewer developers.

But I think that argument starts with a flawed assumption.

It assumes the amount of software we need to build is constant.

It isn't.

If a development team becomes ten times more productive, why assume they'll simply build the same things with fewer people? Why not build more, tackle problems that were previously too expensive or complicated, or develop products we couldn't even consider a few years ago?

AI doesn't just make developers faster. It expands what developers are capable of building.

Of course, team structures will change. Some responsibilities will disappear, others will emerge, and smaller teams may accomplish what previously required entire departments. But increased productivity also creates opportunities to build more ambitious systems.

I believe the most valuable engineers will increasingly become architects and operators of AI-powered development environments. They'll need to understand how to design, orchestrate, validate, and continuously improve these systems.

Knowing how to write good software will remain important. But knowing how to build an environment that consistently produces good software may become even more valuable.

Adapt or Get Left Behind

You don't have to like AI. You can hate the hype, question the quality, and miss spending your days writing code. Trust me, I understand.

But refusing to adapt won't stop the industry from changing.

I think developers who insist that manually writing code is what makes them valuable are making a dangerous bet. The ability to reason about complex systems, understand business requirements, and make sound technical decisions will remain essential. But actually typing that software into an editor is becoming a smaller part of the job.

The real engineering challenge is increasingly about building systems capable of producing reliable software repeatedly, efficiently, and at a scale we couldn't previously achieve.

Just as industrial manufacturing didn't eliminate the need for automotive engineers, I don't believe AI will eliminate the need for software engineers. But it will fundamentally change what we engineer.

And the teams that recognize this early will have a significant advantage.

We spent decades learning how to build software. Now it's time to learn how to build the factories.

[Boost]

Martin Persson — Mon, 27 Oct 2025 12:09:37 +0000

Martin Persson

Oct 18 '25

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

#typescript #nextjs #webdev #saas

4 min read

If you're building SaaS, learning how monorepos work or just want to see how modern TypeScript apps are structured. Orion Kit shows you the full stack: Next.js 15, Drizzle ORM, Stripe payments & JWT auth. Hope it's helpful!

Martin Persson — Tue, 21 Oct 2025 08:14:31 +0000

Martin Persson

Oct 18 '25

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

#typescript #nextjs #webdev #saas

4 min read

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Martin Persson — Sat, 18 Oct 2025 14:42:31 +0000

TL;DR – Open-source monorepo template with Next.js 15, JWT auth, Stripe payments, PostgreSQL (Neon), Drizzle,complete documentation and much more. Designed to make the initial setup overhead for TypeScript SaaS projects simple while keeping strict end-to-end types.

What This Is

Orion Kit is a TypeScript monorepo template that includes the infrastructure most SaaS applications need: user authentication, payment processing, database with migrations, transactional emails, analytics, and background jobs. These systems are pre-configured and integrated, but the template also makes it easy to add features like AI integration, file uploads, i18n, CMS, real-time updates, or rate limiting.

The architecture demonstrates type-safe full-stack development where database schemas automatically generate TypeScript types used throughout your API and frontend—eliminating type mismatches and keeping your codebase in sync as you evolve your data model.

What’s Inside

Applications (4)

Marketing site – /apps/web (port 3000): Landing page & public marketing.
Dashboard – /apps/app (port 3001): Authenticated UI with tasks, billing, basic analytics.
API – /apps/api (port 3002): REST endpoints with auth middleware and Stripe webhooks.
Documentation – /apps/docs (port 3004): Astro Starlight docs.

Shared Packages (9)

@workspace/auth – JWT authentication & user management.
@workspace/database – Drizzle ORM with Neon PostgreSQL (migrations & schema).
@workspace/types – Shared TypeScript types across apps & packages.
@workspace/ui – shadcn/ui component library.
@workspace/payment – Stripe subscriptions & Billing Portal utilities.
@workspace/email – Resend integration with React Email templates.
@workspace/analytics – PostHog event tracking helpers.
@workspace/observability – Axiom logging & error reporting.
@workspace/jobs – Trigger.dev background job processing.

Technical Architecture

Type Safety Flow

Single Source of Truth: the database schema.

Define tables & columns in Drizzle.
Drizzle generates TypeScript types from PostgreSQL.
Those types flow through @workspace/database → API validation (Zod) → frontend forms (React Hook Form + Zod) → UI components.

Result: If you rename a DB column, TypeScript flags every affected usage across the monorepo. No silent mismatches between layers.

PostgreSQL (Neon) → Drizzle schema → Drizzle types → API handlers → Zod validators → React forms/components

Monorepo Structure

Orchestrated by Turborepo. Apps import from shared packages using the workspace protocol (@workspace/*) for code reuse with clear boundaries.

.
├─ apps/
│  ├─ web/         # marketing (Next.js 15)
│  ├─ app/         # dashboard (Next.js 15)
│  ├─ api/         # REST API (Next.js 15 / Route Handlers)
│  ├─ studio/      # Drizzle Studio to interact with the database
│  └─ docs/        # documentation (Astro Starlight)
├─ packages/
│  ├─ auth/
│  ├─ database/
│  ├─ types/
│  ├─ ui/
│  ├─ payment/
│  ├─ email/
│  ├─ analytics/
│  ├─ observability/
│  └─ jobs/
└─ turbo.json / package.json / tsconfig.json / .env* / etc.

Integrated Features

Authentication

Custom JWT implementation with protected routes.
Sessions managed server-side; token stored client-side (e.g., localStorage).
Middleware auto-protects authenticated routes.

Payments

Stripe Checkout for subscriptions.
Webhook handlers for payment lifecycle events.
Billing Portal integration out of the box.
Centralized pricing configuration & subscription helpers in @workspace/payment.

Database

Serverless PostgreSQL via Neon.
Drizzle ORM for type-safe queries & migrations (version controlled).
Comes with a basic DB Studio config for quick inspection.

Email

Resend for transactional email.
React Email templates with a welcome sequence and extensible template system.

Testing

Vitest for unit tests.
Playwright for end-to-end tests (auth flow & critical navigation paths).

Observability & Analytics

PostHog for product analytics (SDK wired to middleware & app events).
Axiom for logs & error reporting (server + edge).

Background Jobs

Trigger.dev orchestrates background tasks from @workspace/jobs.

Development Workflow

Run all apps concurrently with hot reload; changes in packages are instantly reflected in dependents thanks to Turborepo + workspace linking.

App	Path	Port
Marketing	`/apps/web`	3000
Dashboard	`/apps/app`	3001
API	`/apps/api`	3002
Docs	`/apps/docs`	3004

Required Services (all have generous free tiers)

Neon – PostgreSQL hosting
Stripe – Payments
Resend – Email delivery
PostHog – Analytics
Axiom – Logging & monitoring

Stripe CLI to test payments locally

Configuration examples for each live in the docs and .env.example files.

Getting Started

Prerequisites

Node 20+
pnpm (recommended)
Accounts/keys for: Neon, Stripe, Resend, PostHog, Axiom

1) Clone & install

pnpm i

2) Environment variables

Copy the example and fill in values:

cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/app/.env.example apps/app/.env
cp apps/web/.env.example apps/web/.env
cp apps/docs/.env.example apps/docs/.env

See /apps/docs for service-by-service setup. Stripe requires adding webhook secrets; Neon requires a database URL; etc.

3) Database

pnpm db:generate   # drizzle generate
pnpm db:migrate    # run migrations

4) Dev servers

pnpm dev           # starts web (3000), app (3001), api (3002), docs (3004)

5) Tests

pnpm test          # unit (Vitest)
pnpm test:e2e      # e2e (Playwright)

Documentation

Built with Astro Starlight (Markdown, searchable) at /apps/docs.

Coverage:

Quick start
Architectural decisions & data flow
Package API references
Integration guides (AI, CMS, i18n, file uploads, etc.)
Testing strategies
Deployment instructions

Use Cases

Great as a starting point for:

SaaS with auth & subscriptions
Internal tools with role-based access & analytics
MVPs where infra setup must be minimal
Learning resource for modern TypeScript architecture

Licensed under MIT for unrestricted use & modification.

Deployment (Overview)

Web/App/API → Vercel (or similar). Route Handlers power REST & webhooks.
Database → Neon (serverless Postgres).
Stripe → Set live keys & webhook endpoints.
Resend → Configure domain & production API key.
PostHog/Axiom → Set environment keys; verify event/log flow.

Detailed, step-by-step instructions are in the docs.

Contributing

Contributions & feedback are welcome! Feel free to open Issues and PRs. Please include:

Clear description of the change
Screenshots (for UI)
Tests where applicable

Build something you’re proud of. Launch it into orbit. 🚀

[Boost]

Martin Persson — Mon, 25 Aug 2025 11:04:56 +0000

Martin Persson

Aug 19 '25

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

#webdev #typescript #graphql #backend

8 min read

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

Martin Persson — Tue, 19 Aug 2025 09:46:57 +0000

Building a Robust Backend with Effect, GraphQL, and Drizzle

Link to Github repo

Introduction
The Problem
The Solution
- Effect: Functional Effects for Robust Error Handling
- Gradual Migration: Mix Effect and Promises
- Branded Types: Type Safety That Actually Works
Architecture Overview
- Domain Layer
- Repository Layer
Key Features
- Robust Error Handling
- Performance Optimizations
- Circular Relationship Prevention
- Tree Operations
Important Disclaimer: This is a Demo
Benefits
- Compile-Time Safety
- Debugging-Friendly
- Testable Code
- Maintainable
Getting Started
- Available Scripts
- GraphQL API
Key Takeaways
Conclusion

Introduction

This post demonstrates how to build a type-safe, robust backend using Effect, GraphQL, and Drizzle ORM. I built a hierarchical ticket management system to showcase functional programming principles in a real-world application.

The project shows how to handle complex business logic with proper error handling, type safety, and gradual migration from existing codebases. It's designed to be educational rather than production-optimized.

The Problem

Most backend applications suffer from:

Silent failures: Errors get swallowed by generic catch blocks
Type safety theater: TypeScript types that don't actually prevent runtime errors
Tight coupling: Business logic mixed with infrastructure concerns
Poor error handling: Generic error messages that don't help debugging
Difficult testing: Business logic entangled with side effects
Hard to reason about: Complex async flows that are hard to follow

The Solution

A ticket management system that handles hierarchical data with proper error handling and type safety. The system supports:

Hierarchical ticket structures (parent-child relationships)
Cascade operations (toggle, delete entire subtrees)
Circular relationship prevention
Parallel processing for performance
Comprehensive error handling with specific error types

1. Effect: Functional Effects for Robust Error Handling

Effect is a TypeScript library that brings functional programming principles to the real world. Instead of throwing errors or returning null, Effect forces you to handle all possible outcomes explicitly.

// Traditional approach - fragile
const findTicket = (id: number) => {
  const ticket = database.find(id);
  if (!ticket) throw new Error("Not found");
  return ticket;
}

// Effect approach - robust
const findTicket = (id: TicketId) =>
  Effect.gen(function* () {
    const ticket = yield* repository.findById(id);
    return yield* Effect.flatMap(
      ticket,
      Option.match({
        onNone: () => Effect.fail(new TicketNotFoundError(`Failed to find ticket with ID ${id}`)),
        onSome: Effect.succeed,
      })
    );
  });

Effect provides several benefits:

Explicit error handling: All possible failure cases must be handled
Composable operations: Chain operations together safely
Dependency injection: Services are injected through layers
Type safety: Compile-time guarantees about error handling

2. Gradual Migration: Mix Effect and Promises

You don't need to rewrite everything at once. The adapter allows mixing Effect-based and Promise-based resolvers:

export const enableEffectResolvers = (schema: GraphQLSchema) => {
  return mapSchema(schema, {
    [MapperKind.ROOT_FIELD]: (fieldConfig) => {
      const originalResolver = fieldConfig.resolve
      if (!originalResolver) {
        return fieldConfig
      }
      return {
        ...fieldConfig,
        async resolve(parent, args, context, info) {
          const result = originalResolver(parent, args, context, info)

          if (Effect.isEffect(result)) {
            return await Effect.runPromise(result.pipe(Effect.provide(AppLayer)))
          }

          // This adapter allows mixing Effect and Promise-based resolvers in the same codebase.
          // If the resolver returns a Promise instead of an Effect, it will be executed as-is.
          // This enables incremental migration from Promise-based to Effect-based code without
          // requiring a complete rewrite of all resolvers at once.
        },
      }
    },
  })
}

This approach enables:

Incremental adoption: Start with new features using Effect
Risk mitigation: Keep existing code working while migrating
Team learning: Gradually introduce functional concepts
Proof of concept: Demonstrate benefits before full migration

3. Branded Types: Type Safety That Actually Works

Instead of using plain numbers for IDs, branded types prevent mixing up different kinds of IDs:

export type TicketId = number & Brand.Brand<"TicketId">

export const TicketIdSchema = Schema.NumberFromString.pipe(
  Schema.int(),
  Schema.nonNegative(),
  Schema.brand("TicketId")
)

This means you can't accidentally pass a UserId where a TicketId is expected - TypeScript will catch it at compile time.

Benefits of branded types:

Prevent bugs: TypeScript catches ID mixing at compile time
Self-documenting: Code clearly shows what type of ID is expected
Refactoring safety: Changes to ID types are caught immediately
Better IDE support: Autocomplete and error detection work correctly

Architecture Overview

The project follows a clean architecture pattern with clear separation of concerns:

domain/           # Business logic, models, schemas
├── ticket/
│   ├── model.ts      # Drizzle table definitions
│   ├── schema.ts     # Input validation & branded types
│   ├── service.ts    # Business logic
│   ├── repository.ts # Database access
│   └── helpers.ts    # Tree manipulation utilities
graphql/          # API layer
├── resolvers/    # GraphQL resolvers with error handling
└── schema/       # GraphQL type definitions
lib/              # Infrastructure
├── db.ts         # Database setup
└── utils.ts      # Response helpers
adapter/          # Integration layer
└── effectAdapter.ts # Effect integration with GraphQL

Domain Layer

The domain layer contains all business logic and is completely independent of infrastructure concerns:

export class TicketService extends Effect.Service<TicketService>()("Ticket/Service", {
  effect: Effect.gen(function* () {
    const repository = yield* TicketRepository
    const helper = yield* HelperService

    const toggleTicket = (input: typeof ToggleTicketInput.Type) =>
      Effect.gen(function* () {
        // Business logic here
      })

    return {
      findById,
      createTicket,
      findAll,
      deleteTicket,
      toggleTicket,
      removeParentFromTicket,
      setParentOfTicket,
      addChildrenToTicket,
    } as const
  }),
  dependencies: [TicketRepository.Default, HelperService.Default],
})

Repository Layer

The repository layer handles database operations with proper error handling:

export class TicketRepository extends Effect.Service<TicketRepository>()("Ticket/Repo", {
  effect: Effect.gen(function* () {
    const db = yield* SqliteDrizzle.SqliteDrizzle

    const findById = (id: TicketId) => {
      return Effect.gen(function* () {
        const rowsResult = yield* db.select().from(tickets).where(eq(tickets.id, id))
        return Option.fromNullable(rowsResult[0])
      })
    }

    return {
      findById,
      createTicket,
      deleteTicket,
      findAll,
      toggleTicket,
      findChildren,
      removeParent,
      setParent,
    } as const
  }),
  dependencies: [DatabaseLive],
})

Key Features

Robust Error Handling

Every operation has comprehensive error handling with specific error types:

Effect.catchTags({
  ParseError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`❌ Invalid input format: ${error.message}`);
    return yield* errorResponse(`Invalid parameters. Please check your input.`);
  }),
  TicketNotFoundError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`🔍 Ticket not found: ${error.message}`);
    return yield* errorResponse(`Ticket not found. Cannot perform operation on non-existent ticket.`);
  }),
  CircularRelationshipError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`🔄 Circular relationship detected: ${error.message}`);
    return yield* errorResponse(`Cannot create circular parent-child relationship.`);
  }),
  TimeoutException: (error) => Effect.gen(function* () {
    yield* Effect.logError(`⏰ Operation timeout: ${error.message}`);
    return yield* errorResponse(`Operation took too long. Please try again.`);
  }),
  SqlError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`�� Database error: ${error.message}`);
    return yield* errorResponse(`Database connection issue. Please try again later.`);
  }),
});

Performance Optimizations

Parallel processing for operations that affect multiple tickets:

yield* Effect.forEach(
  allTickets,
  (ticket) => repository.toggleTicket({ id: ticket.id as TicketId, isCompleted: input.isCompleted }),
  { concurrency: 5 }
);

Circular Relationship Prevention

The system prevents circular relationships in the ticket hierarchy:

const checkCircularRelationships = (childId: TicketId, parentId: TicketId) =>
  Effect.gen(function* () {
    const visited = new Set<TicketId>([childId])
    let currentId = parentId

    while (true) {
      if (visited.has(currentId)) {
        return yield* Effect.fail(
          new CircularRelationshipError(
            `Circular relationship detected: setting ticket ${childId} as parent of ${parentId} would create a cycle`
          )
        )
      }
      visited.add(currentId)

      const current = yield* repository.findById(currentId)
      const result = Option.match(current, {
        onNone: () => false,
        onSome: (ticket) => {
          if (ticket.parentId === null) {
            return false
          }
          currentId = ticket.parentId as TicketId
          return true
        },
      })

      if (!result) {
        return yield* Effect.void
      }
    }
  })

Tree Operations

The system supports complex tree operations like cascade toggle and delete:

const enrichTicketTree = (rootTicket: Ticket, maxDepth = 10) =>
  Effect.gen(function* () {
    const queue = yield* Queue.unbounded<TicketWithChildren>()
    const withChildren = yield* getMaybeChildren(rootTicket)
    yield* Queue.offer(queue, withChildren)

    let depth = 0

    while (depth++ < maxDepth) {
      const currentLevel = yield* Queue.takeUpTo(queue, 100)

      for (const ticket of currentLevel) {
        if (ticket.children.length > 0) {
          for (const child of ticket.children) {
            const enriched = yield* getMaybeChildren(child)
            yield* Queue.offer(queue, enriched)
            ticket.children = ticket.children.map((child) => (child.id === enriched.id ? enriched : child))
          }
        }
      }

      if (currentLevel.length === 0) {
        break
      }
    }

    return withChildren
  })

Important Disclaimer: This is a Demo

This ticket system is designed to showcase Effect and functional programming principles, not to be the most efficient ticket management system.

For example, I'm doing recursive tree traversal and multiple database calls where a few well-crafted SQL queries could do the same job more efficiently. But that would defeat the purpose of demonstrating Effect's capabilities.

The goal is to show how Effect can handle complex business logic with proper error handling, not to optimize for database performance.

Benefits

1. Compile-Time Safety

TypeScript catches most errors before runtime, and Effect ensures all error cases are handled:

Type safety: Branded types prevent ID mixing
Error handling: All failure cases must be explicitly handled
Dependency injection: Services are properly injected and typed
Composition: Operations can be safely composed

2. Debugging-Friendly

Specific error types and comprehensive logging:

🔄 Starting cascade toggle for ticket ID: 1 to true
 Toggling 6 tickets to true
✅ Cascade toggle completed: 6 tickets updated

The logging system provides:

Structured logs: Each operation is clearly logged
Error context: Specific error types with meaningful messages
Operation tracking: Easy to follow the flow of operations
Performance insights: Timing and concurrency information

3. Testable Code

The functional approach makes testing straightforward:

describe("TicketService", () => {
  describe("findById", () => {
    it("should find a ticket by id", async () => {
      const TicketServiceMock = new TicketService({
        ...DefaultServiceMockImplementation,
        findById: vi.fn().mockReturnValue(
          Effect.succeed({
            id: 1 as TicketId,
            title: "Test Ticket",
            description: "Test Description",
            parentId: null,
            completed: false,
            createdAt: new Date(),
            updatedAt: new Date(),
          })
        ),
      })

      const result = await Effect.runPromise(
        Effect.gen(function* () {
          const ticketService = yield* TicketService
          const ticket = yield* ticketService.findById(1 as TicketId)
          return ticket
        }).pipe(Effect.provide(Layer.succeed(TicketService, TicketServiceMock)))
      )

      expect(result.title).toBe("Test Ticket")
      expect(TicketServiceMock.findById).toHaveBeenCalledWith(1)
    })
  })
})

Benefits of this testing approach:

Pure functions: Easy to test business logic in isolation
Mockable dependencies: Services can be easily mocked
Type safety: Tests benefit from the same type safety as production code
Comprehensive coverage: All error cases can be tested

4. Maintainable

Clear separation of concerns and explicit error handling make the codebase easy to understand and modify:

Separation of concerns: Business logic, data access, and API layers are separate
Explicit dependencies: All dependencies are clearly declared
Consistent patterns: Effect patterns are used consistently throughout
Documentation: Code is self-documenting through types and structure

Getting Started

git clone <repository>
npm install
npm run db:seed
npm run dev

The system comes with a comprehensive GraphQL API at http://localhost:4000.

Available Scripts

npm start: Start the production server
npm run dev: Start the development server with hot reload
npm run db:seed: Seed the database with sample data
npm run db:drop: Delete the database file
npm run db:reset: Reset the database (drop + seed)
npm test: Run tests
npm run test:watch: Run tests in watch mode
npm run test:coverage: Run tests with coverage

GraphQL API

The API provides the following operations:

Queries:

findAll: Get root tickets with pagination
findById: Get a specific ticket with its complete tree

Mutations:

createTicket: Create a new root ticket
toggleTicket: Toggle completion status (cascade)
deleteTicket: Delete a ticket and all descendants
removeParentFromTicket: Convert child to root ticket
setParentOfTicket: Move ticket to new parent
addChildrenToTicket: Add multiple children to a parent

Key Takeaways

Functional programming solves real problems in production code
Gradual migration is possible - you don't need to rewrite everything at once
Type safety matters - branded types prevent entire classes of bugs
Error handling should be explicit - don't let errors slip through the cracks
Effect works great with existing tools - Apollo GraphQL Server, Drizzle ORM, etc.
Testing becomes easier with pure functions and explicit dependencies
Code is more maintainable with clear separation of concerns
Debugging is improved with structured logging and specific error types

Conclusion

Effect, combined with GraphQL and Drizzle, creates a development experience that's both productive and reliable. The functional approach forces you to handle errors explicitly while maintaining type safety throughout the application.

The gradual migration approach makes it practical to adopt these patterns in existing codebases, while the comprehensive error handling and testing capabilities make the resulting code more robust and maintainable.

This approach isn't just about using trendy functional programming concepts - it's about building software that's easier to reason about, test, and maintain in the long run.

Building a Real-Time Chat App with Firebase and Next.js

Martin Persson — Wed, 23 Apr 2025 17:46:29 +0000

Introduction
Tech Stack
Project Overview
Firebase Setup
Message Schema with Zod
Real-Time Messaging with Firestore
Pagination and Lazy Loading
Scroll Behavior
UI with shadcn/ui and Tailwind
Handling Edge Cases
Conclusion

Introduction

This post walks through the process of building a modern real-time chat application using Next.js, Firebase Firestore, and Tailwind CSS. The app allows users to enter a display name and join a live chat where messages are synced instantly across clients. It supports lazy loading of older messages, smooth scroll behavior, and a clean, responsive UI built with minimal dependencies.

View the repository on GitHub

Tech Stack

Next.js for the React framework
Firebase Firestore for real-time database
Tailwind CSS for styling
shadcn/ui for prebuilt UI components
Zod for runtime validation of messages

Project Overview

The chat app begins with a simple prompt asking for your display name. Once submitted, you're taken to the main chat interface. It displays the 25 most recent messages by default and anchors the view to the bottom. As users scroll up, older messages are fetched and added seamlessly. All messages are updated in real-time using Firestore subscriptions, ensuring that new content appears instantly across all clients.

Firebase Setup

To get started with Firebase and Firestore:

1. Create a Firebase project:

Go to Firebase Console.
Click “Add project” and follow the setup wizard (you can skip Google Analytics).

2. Add Firestore to your project:

In the Firebase Console, navigate to Build > Firestore Database.
Click “Create database”, select Start in test mode, and choose your region.

3. Create a Web App in Firebase:

Go to Project Settings > General.
Scroll down to “Your apps” and click the </> icon to add a new web app.
Register your app and Firebase will generate your configuration object.

4. Set up environment variables:

In your project root, create a file named .env.local and add the following using your config values:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_COLLECTION=your_unique_collection_name

5. Initialize Firebase in your app:

Create a file like lib/firebase.ts:

import { initializeApp } from "firebase/app"
import { getFirestore } from "firebase/firestore"

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
}

const app = initializeApp(firebaseConfig)
export const db = getFirestore(app)

You're now ready to use Firestore to store and retrieve chat messages in real time.

Message Schema with Zod

In this project, we take a code-first approach when working with Firestore. Instead of relying on Firestore rules or ad-hoc validation, we define the shape and structure of a valid message directly in our application code using Zod.

Zod is a TypeScript-first schema declaration and validation library. It allows us to describe the expected structure of a message object and ensure that any data coming from or going to Firestore matches this schema.

This improves data consistency and safety. For example, it prevents malformed data from being saved or rendered, and avoids bugs caused by missing or invalid fields.

Here’s the schema definition:

import { z } from "zod"
import { Timestamp } from "firebase/firestore"

export const messageSchema = z.object({
  id: z.string(),
  text: z.string().min(1),
  sender: z.string(),
  timestamp: z.instanceof(Timestamp),
})

export type Message = z.infer<typeof messageSchema>

We use this schema in three main places:

When sending messages – to ensure the message has the right shape before adding it to Firestore.
When fetching messages – to validate all messages returned from Firestore queries.
When listening to new messages in real time – to discard or warn about any data that doesn’t match the schema.

This helps enforce strict typing and protects your frontend from unexpected data issues, especially in real-time applications.

Real-Time Messaging with Firestore

To enable real-time chat functionality, the app leverages Firestore’s onSnapshot() method. This sets up a listener on the collection that receives updates whenever new documents (messages) are added that match the query criteria.

In our implementation, we subscribe only to messages with a timestamp greater than the most recent message already displayed. This prevents re-fetching old messages. Every new message is parsed and validated with zod before it's added to the UI, ensuring both real-time updates and schema safety.

Pagination and Lazy Loading

The chat is optimized for performance and user experience using a lazy loading strategy. On initial load, the app fetches only the 25 most recent messages using a descending order query. These are then reversed to maintain chronological order.

When the user scrolls upwards, additional older messages are fetched using startAfter(lastDoc) to avoid duplicates. This paginated approach ensures scalability and smooth UX without overloading the UI with too many messages at once.

Scroll Behavior

The scroll behavior is intelligently managed:

On first load or when a new message is sent/received, the chat automatically scrolls to the bottom.
When loading older messages, the app maintains the user's current scroll position to avoid disorienting jumps.

This logic provides a seamless experience, especially in long conversations, and mimics the behavior of popular chat apps.

UI with shadcn/ui and Tailwind

The user interface is built using components from shadcn/ui, a utility-focused library that integrates seamlessly with Tailwind CSS. For example, we use Textarea for message input and Button for actions like sending messages. These components provide a clean foundation with minimal styling, allowing us to maintain design consistency while focusing on function.

Tailwind CSS is used throughout for layout and spacing. It ensures that the chat UI is responsive and visually balanced across different screen sizes without the need for custom CSS.

Handling Edge Cases

To provide a smooth and robust user experience, several edge cases are considered and handled:

Empty Chats: If there are no messages yet, the app handles the empty state gracefully without crashing or rendering errors.
Realtime Handling of Own Sent Message: Messages sent by the current user appear instantly and are not duplicated when received via the real-time listener.
Debouncing Scroll Fetches: Scroll-triggered fetching of older messages is debounced to avoid spamming the backend with requests.
Avoiding Duplicate Message Entries: Before adding any new message to the list, the app checks for existing message IDs to prevent duplicates in the UI.

Conclusion

This project demonstrates how to build a full-featured real-time chat app using Firebase Firestore, Next.js, and modern UI tools like Tailwind CSS and shadcn/ui.

It showcases best practices such as:

Code-first schema validation with Zod
Real-time data updates using Firestore subscriptions
Efficient lazy loading and scroll handling
Clean and minimal UI with reusable components

The architecture is intentionally kept simple and readable to emphasize clarity over complexity. Whether you're testing this for a coding challenge or building on top of it for a larger project, this foundation provides a strong starting point.

Feel free to reach out with questions, feedback, or suggestions. I'd love to hear what you think!

Discriminated Unions in C# with OneOf – Azure Functions

Martin Persson — Mon, 24 Mar 2025 22:03:48 +0000

🧠 What Are Discriminated Unions?

A discriminated union is a type that can represent one of several distinct outcomes, but never more than one at a time. They are native to F#, Rust, TypeScript, and other functional languages.

In C#, we simulate this using the excellent OneOf library.

🧼 Why Classic C# Fails Here

Pattern	Why it's bad
`null`	No context — what went wrong?
`bool TryX(out T)`	Hard to read, hard to test
`try/catch` as logic	Expensive, messy, and often misused
Exception everywhere	Breaks flow, pollutes logic

✅ Why OneOf Is Better

Type-safe return values
Explicit control over outcomes
Functional-style .Match(...)
Easier to test, reason about, and maintain
Avoids throwing exceptions for flow control

🛠 Setup

dotnet new azure-functions -n OneOfDemo --worker-runtime dotnetIsolated
cd OneOfDemo
dotnet add package OneOf

📦 Define Your Result Types

public record User(int Id, string Name);
public record NotFoundError(string Message);
public record TimeoutError(string Message);
public record ValidationError(string Message);
public record UnknownError(string Message);

🔧 Build the Service Layer

public class UserService
{
    private readonly HttpClient _http = new()
    {
        BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
    };

    public async Task<OneOf<User, NotFoundError, TimeoutError, UnknownError, ValidationError>> GetUserByIdAsync(int id)
    {
        if (id <= 0)
            return new ValidationError("Id must be greater than 0.");
        if (id == 99)
            return new TimeoutError("Simulated timeout.");
        if (id == 42)
            return new UnknownError("Simulated crash.");

        try
        {
            var response = await _http.GetAsync($"/users/{id}");
            if (!response.IsSuccessStatusCode)
                return new NotFoundError("User not found.");

            var user = await response.Content.ReadFromJsonAsync<User>();
            return user ?? new NotFoundError("User not found.");
        }
        catch (Exception ex)
        {
            return new UnknownError($"Unexpected error: {ex.Message}");
        }
    }
}

🚀 Azure Function Using Match

[Function("GetUserById")]
public async Task<HttpResponseData> Run(
  [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "users/{id:int}")] HttpRequestData req,
  int id)
{
    var result = await _service.GetUserByIdAsync(id);

    return await result.Match<Task<HttpResponseData>>(
        async user => req.CreateJsonResponse(HttpStatusCode.OK, user),
        async notFound => req.CreateJsonResponse(HttpStatusCode.NotFound, new { error = notFound.Message }),
        async timeout => req.CreateJsonResponse(HttpStatusCode.RequestTimeout, new { error = timeout.Message }),
        async unknown => req.CreateJsonResponse(HttpStatusCode.InternalServerError, new { error = unknown.Message }),
        async validation => req.CreateJsonResponse(HttpStatusCode.BadRequest, new { error = validation.Message })
    );
}

🧼 Extension Method

public static class HttpResponseExtensions
{
    public static async Task<HttpResponseData> CreateJsonResponse<T>(this HttpRequestData req, HttpStatusCode status, T body)
    {
        var response = req.CreateResponse(status);
        await response.WriteAsJsonAsync(body);
        return response;
    }
}

🧪 Unit Testing With OneOf

[Fact]
public async Task Returns_ValidationError_When_Id_Is_Zero()
{
    var service = new UserService();
    var result = await service.GetUserByIdAsync(0);

    Assert.True(result.IsT4); // ValidationError
    Assert.Equal("Id must be greater than 0.", result.AsT4.Message);
}

You can test any path: .IsT0, .IsT1, .IsT2... depending on position in OneOf.

🧠 Benefits of This Approach

No need for null checks
No exception-based flow
Clear separation of responsibilities
Total control over error behavior
Greatly improved testability

🧨 Common Mistakes

Mistake	What to do instead
Returning null	Return a specific error type
Throwing errors everywhere	Return values like `TimeoutError`
Using try/catch for flow	Use `.Match(...)` and OneOf types
Skipping tests for errors	Test each OneOf case with `.IsTn`

📐 Architecture Tips

Put all error types in an Errors/ folder
Use record for immutability and clarity
Use OneOf everywhere instead of throwing
Keep Azure Function logic lean — let services do the work

🔚 Final Thoughts

This pattern is not just syntactic sugar — it changes how you think about control flow, responsibility, and correctness.

Using OneOf + Azure Functions:

You get full control of your return paths
You write less error-prone code
You make every function explicit and testable

And it still feels like C#.

📚 Resources

OneOf GitHub: https://github.com/mcintyre321/OneOf
Example code: https://github.com/Mumma6/azure-function-oneof

Building Robust Typescript APIs with the Effect Ecosystem

Martin Persson — Tue, 02 Jul 2024 13:22:13 +0000

Introduction

In this post, we will explore how to create a complete API using the Effect ecosystem. Although the Effect documentation is excellent, there are not many examples of full applications.

If you have never heard of Effect, I suggest you take a look at the website: https://effect.website/

Effect is not just another framework but instead acts as the missing standard library for TypeScript. Because of this, I believe Effect is truly the future for TypeScript, especially when considering the challenges associated with writing production-ready applications in "plain" TypeScript. To understand more about these challenges and how Effect addresses them, watch this insightful video by Johannes Schickling, the founder of Prisma: https://www.youtube.com/watch?v=PxIBWjiv3og&ab_channel=Effect%7CTypeScriptatScale.

The purpose of this post is to demonstrate how to use the different components of the Effect ecosystem to build a modern API:

Effect: The core module for handling and creating effects.
Effect Schema: Use schemas to validate and transform data.
Effect SQL: A toolkit for integration with SQL databases. We will use PostgreSQL in our example.
Effect Platform/Node: Allows us to use the Node.js platform. We will use this to create our server, router, and handle external API calls.
Effect opentelemetry: Lets us get tracing and metrics for our app. We integrate it to our console but its really easy to setup in honeycomb for example

By utilizing these modules from Effect, we gain massive benefits. Everything is type-safe, we have robust error handling, and there's no need to reach out to NPM for specific packages. Everything is included in Effect.

Make sure you clone the GitHub repo to see the complete code.
Link to repo: https://github.com/Mumma6/effect-node-server

Overview of the Project

This project involves building a straightforward application that allows you to create user profiles and add movies to these profiles. It incorporates basic CRUD (Create, Read, Update, Delete) operations, external API calls with movie details fetched from the OMDb API. All data, including user profiles and associated movie information, is stored in a PostgreSQL database.

The system's design is inspired by Domain-Driven Design (DDD), where "User" and "Movie" are treated as distinct domains. This approach facilitates managing complex functionalities and maintaining clear boundaries between different areas of concern within the application making it an excellent starting point and foundation to build upon.

Design

Domain Layer

The domain layer is divided into user and movie domains, each containing the following sub-layers:

Models: Define the data structures and schemas.
Repositories: Handle data access and database operations.
Infrastructure: Handle external API calls (movie only).
Services: Implement business logic and orchestrate calls to repositories and external APIs (for the movie domain).

Routes Layer

The routes layer defines the HTTP routes for the API. Each domain has its own set of routes:

User Routes: Handles user-related operations (create, read, update, delete).
Movie Routes: Handles movie-related operations (create, read, update, delete) and integrates with the OMDb API.

Lib Layer

The lib layer contains configuration and setup for the database:

Database: Contains configuration and initialization logic for connecting to PostgreSQL using the Effect library.

Entry Point

index.ts: The main entry point of the application. It initializes the application by setting up routes and starting the server.

Code

Rather than guiding you through a step-by-step coding tutorial, I'll highlight crucial code snippets from our project. This approach will focus on explaining the concepts and the architecture behind the implementation, offering insights into how the Effect ecosystem seamlessly integrates into our application.

Dependencies

The project uses these dependencies

"dependencies": {
    "@effect/opentelemetry": "^0.34.29",
    "@effect/platform": "^0.58.16",
    "@effect/platform-node": "^0.53.15",
    "@effect/schema": "^0.68.14",
    "@effect/sql": "^0.4.16",
    "@effect/sql-pg": "^0.4.16",
    "@opentelemetry/sdk-metrics": "^1.25.1",
    "@opentelemetry/sdk-trace-base": "^1.25.1",
    "@opentelemetry/sdk-trace-node": "^1.25.1",
    "dotenv": "^16.4.5",
    "effect": "^3.4.5",
    "ts-node-dev": "^2.0.0",
    "typescript": "^5.5.2"
  }

Entry point

In our index.ts, we initialize the server and the router. We provide all the necessary Layers for the project, similar to "dependency injection." This setup ensures that each component has access to the resources it needs to function correctly.

We also have the ability to add our custom middleware. Notably, the NodeRuntime.runMain function acts as the starting point of our entire application. This function boots up the server, ensuring that all configurations and services are loaded and ready to handle requests.

import { HttpMiddleware, HttpRouter, HttpServer, HttpServerResponse } from "@effect/platform"
import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
import { Effect, Layer } from "effect"
import { createServer } from "http"
import { DatabaseInitialisation, SqlLive } from "./lib/database"
import { AppRouter } from "./routes/routes"

import { UserService } from "./domain/user/service/user.service"
import { MovieService } from "./domain/movies/service/movie.service"
import { TracingConsole } from "./lib/tracing"

const myLogger = HttpMiddleware.make((app) =>
  Effect.gen(function* () {
    console.log("LOGGED")
    return yield* app
  })
)
const ServerLive = NodeHttpServer.layer(createServer, { port: 5000, host: "localhost" })

const HttpLive = HttpRouter.Default.unwrap(HttpServer.serve(myLogger)).pipe(
  Layer.provide(AppRouter),
  Layer.provide(ServerLive),
  Layer.provide(UserService.Live),
  Layer.provide(MovieService.Live),
  Layer.provide(DatabaseInitialisation.Live),
  Layer.provide(SqlLive),
  Layer.provide(TracingConsole)
)

NodeRuntime.runMain(Layer.launch(HttpLive))

Lib folder

In the lib directory, we define the structure of our database by creating tables and setting up the connection details for our PostgreSQL client. Typically, you would retrieve these connection details from environment variables specified in your .env file to enhance security and flexibility. However, for simplicity in this demonstration, I have hardcoded them directly into the configuration files.

import { PgClient } from "@effect/sql-pg"
import { Config, Context, Effect, Layer, Redacted } from "effect"

const make = Effect.gen(function* () {
  const sql = yield* PgClient.PgClient

  // Suppress NOTICE messages
  yield* sql`SET client_min_messages TO WARNING;`

  // Create users table if it does not exist
  yield* sql`CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
  );`

  // Create movies table if it does not exist
  yield* sql`CREATE TABLE IF NOT EXISTS movies (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(255) NOT NULL,
    year VARCHAR(4),
    genre VARCHAR(255),
    plot TEXT,
    imdb_id VARCHAR(255),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
  );`
})

export class DatabaseInitialisation extends Context.Tag("DatabaseInitialisation")<DatabaseInitialisation, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

export const SqlLive = PgClient.layer({
  database: Config.succeed("effect"),
  host: Config.succeed("localhost"),
  username: Config.succeed("postgres"),
  port: Config.succeed(5432),
  password: Config.succeed(Redacted.make("123")),
})

In addition to database configurations, our lib directory also sets up tracing to monitor and diagnose application performance. For details on integrating with alternative tracing services like Honeycomb, refer to the GitHub repository.

import * as NodeSdk from "@effect/opentelemetry/NodeSdk"
import { BatchSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base"

export const TracingConsole = NodeSdk.layer(() => ({
  resource: { serviceName: "example" },
  spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter()),
}))

Routing

The routes.ts file plays a crucial role in our application by organizing and managing all the routing configurations. Currently, it handles two primary routes: one for movies and another for users. However, the structure is designed to be extensible, allowing for the easy addition of more routes as the application grows.

Each route is grouped within its respective module, and specific route implementations are equipped with necessary dependencies using the Layer.provide method. This setup ensures that each route has access to the services and data layers it requires to function correctly.

import { HttpRouter } from "@effect/platform"
import { Effect, Layer } from "effect"
import { UserRoutes, UsersRouter } from "./users/users.routes"
import { MoviesRouter, MovieRoutes } from "./movies/movies.routes"

export const AppRouter = HttpRouter.Default.use((router) =>
  Effect.gen(function* () {
    yield* router.mount("/users", yield* UsersRouter.router)
    yield* router.mount("/movies", yield* MoviesRouter.router)
  })
).pipe(Layer.provide(UserRoutes), Layer.provide(MovieRoutes))

The MoviesRouter handles routing for movie-related requests. It's defined as a specialized router with a unique tag, which helps in organizing and isolating movie-related routes within the larger application. Here’s how we define and organize these routes:

export class MoviesRouter extends HttpRouter.Tag("MoviesRouter")<MoviesRouter>() {}

export const MovieRoutes = Layer.mergeAll(GetMovies, CreateMovie, UpdateMovie, GetMovieById, GetMoviesForUserId, DeleteMovieById).pipe(
  Layer.provideMerge(MoviesRouter.Live)
)

In this setup, we use Layer.mergeAll to combine various movie-related route handlers like GetMovies, CreateMovie, and others into a single layer. This layer is then provided to the MoviesRouter using Layer.provideMerge, ensuring that all route handlers have access to the necessary dependencies and configurations.

The GetMovies route demonstrates how we handle a typical GET request to fetch all movies. This route uses services from the domain layer to perform its operations and includes robust error handling to manage potential issues during execution:

import { HttpRouter, HttpServerRequest, HttpServerResponse } from "@effect/platform"
import { Effect, Layer, pipe } from "effect"
import { Schema } from "@effect/schema"
import { MovieService } from "../../domain/movies/service/movie.service"

const GetMovies = MoviesRouter.use((router) =>
  pipe(
    MovieService,
    Effect.flatMap((service) =>
      router.get(
        Routes.All,
        Effect.gen(function* () {
          const movies = yield* service.getAllMovies()
          return yield* HttpServerResponse.json(movies)
        }).pipe(
          Effect.catchTags({
            ParseError: (error) =>
              HttpServerResponse.json({ message: "Invalid request data for fetching all movies", details: error.message }, { status: 400 }),
            SqlError: (error) =>
              HttpServerResponse.json({ message: "Database error while fetching all movies", details: error.message }, { status: 500 }),

            HttpBodyError: (error) =>
              HttpServerResponse.json(
                { message: "Error processing request body while fetching all movies", details: error.reason },
                { status: 400 }
              ),
          }),
          Effect.withSpan("GetAllMoviesRoute")
        )
      )
    )
  )
)

Key Features:

Service Integration: The route integrates with MovieService to fetch all movies, encapsulating business logic and data fetching in a service layer.
Error Handling: Robust error handling is implemented using Effect.catchTags. This method catches and handles different types of errors, allowing the application to respond with appropriate HTTP status codes and error messages:

ParseError: Catches errors related to request data parsing.
SqlError: Handles errors that occur during database operations.
HttpBodyError: Manages errors related to processing the HTTP request body.

Distributed Tracing: Effect.withSpan("GetAllMoviesRoute") is used for adding tracing to monitor the performance and troubleshoot issues in the route execution.

By structuring routes in this manner, we ensure that our application not only efficiently handles operations but also gracefully manages errors, providing clear feedback to the client and maintaining the integrity of the application.

Service

The MovieService is responsible for movie-related functionalities in our application. It acts as an intermediary between the MovieRepository, which handles database operations, and MovieInfrastructure, which deals with external API calls to fetch additional movie details.

Here’s how the service is structured:


const make = Effect.gen(function* () {
  const repository = yield* MovieRepository
  const infrastructure = yield* MovieInfrastructure

  const getAllMovies = () => repository.getAllMovies()

  const getMovieById = (id: string) =>
    pipe(
      repository.GetMovieById(id),
      Effect.map(
        Option.match({
          onNone: () => "Movie not found",
          onSome: (movie) => movie,
        })
      )
    )

  // rest of the service implementations

  return {
    getAllMovies,
    getMovieById,
    createMovie,
    updateMovie,
    deleteMovie,
    getMoviesByUserId,
  } as const
})
export class MovieService extends Context.Tag("MovieService")<MovieService, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

Infrastructure

The MovieInfrastructure layer in our application is specifically designed to handle all external API interactions. In this example, we focus on fetching movie information from the OMDb API, but the structure is scalable to accommodate multiple external API sources as needed. This modularity ensures that extending our application to integrate with additional services is straightforward.

import { Config, Context, Effect, Layer, pipe } from "effect"
import { HttpClientRequest, HttpClient } from "@effect/platform"
import { ApiMovieSchema } from "../models/movie.model"

const basePath = "http://www.omdbapi.com/"

const make = Effect.gen(function* () {
  const key = yield* Config.string("OMDB_KEY")
  const getMovieInformation = (name: string) =>
    pipe(
      HttpClientRequest.get(`${basePath}?t=${name}&apikey=${key}`),
      HttpClient.fetch,
      ApiMovieSchema.decodeResponse,
      Effect.retry({ times: 3 }),
      Effect.withSpan("GetMovieInformation")
    )

  return {
    getMovieInformation,
  } as const
})

export class MovieInfrastructure extends Context.Tag("MovieInfrastructure")<MovieInfrastructure, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

In the "models" directory we define the expected structure of the JSON response from the OMDb API. Each field like Title is mapped directly to the corresponding field in the API response.

Decoding Method: decodeResponse is a static method that wraps around the schema to provide a convenient way to parse and validate the JSON body of the HTTP response. It ensures that the incoming data matches our specified schema, which is critical for maintaining the integrity and consistency of the data used within our application.

export class ApiMovieSchema extends Schema.Class<ApiMovieSchema>("ApiMovieSchema")({
  Title: Schema.String,
  // Many more fields here...
}) {
  static decodeResponse = HttpClientResponse.schemaBodyJsonScoped(ApiMovieSchema)
}

Repository

The repository layer in our application is crucial for handling all database interactions. It uses SQL providers to communicate with the database, leveraging schemas to define the data structures expected from the database responses and to format the data sent in queries.

Here’s how we define and structure the MovieRepository:

import { Schema } from "@effect/schema"
import { PgClient } from "@effect/sql-pg"
import { Context, Effect, Layer } from "effect"
import { SqlResolver, SqlSchema } from "@effect/sql"
import { InsertMovieSchema, Movie, UpdateMovieSchema } from "../models/movie.model"

const make = Effect.gen(function* () {
  const sql = yield* PgClient.PgClient

  const AddMovie = yield* SqlResolver.ordered("InsertMovie", {
    Request: InsertMovieSchema,
    Result: Movie,
    execute: (requests) => sql`INSERT INTO movies ${sql.insert(requests)} RETURNING *`,
  }).pipe(Effect.withSpan("AddMovieResolver"))

  // rest of the implementations

  return {
    addMovie: AddMovie.execute,
    GetMovieById: GetMovieById.execute,
    getAllMovies: GetAllMovies,
    updateMovie: UpdateMovie.execute,
    deleteMovie: DeleteMovie.execute,
    getMovieByUserId: GetMovieByUserId,
  } as const
})
export class MovieRepository extends Context.Tag("MovieRepository")<MovieRepository, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

Conclusion

Throughout this post, we've explored how to build a complete and modern API using the Effect ecosystem. From setting up an organized and efficient routing system to integrating external API services and managing database interactions seamlessly, the Effect library has shown its strength in creating scalable and maintainable backend applications.

The future of Typescript in Production-Grade Applications

Martin Persson — Sat, 30 Mar 2024 11:06:54 +0000

Introduction

Javascript is everywhere and will not be going away anytime soon. I love Javascript, it's the first language I learned, and I use it every day, having done so for the past 7 years. But I think we can all agree that the language has many flaws, especially with error handling, callback hell, type coercion and many more. Alot of improvments have been made over time tho.

Typecript was introduced as a superset of Javascript, aimed at addressing many of Javascript's flaws through the introduction of static typing. These days, pure Javascript applications are becoming increasingly rare. The vast majority of new projects opt for Typescript for its robust typing system that improves code reliability and maintainability.

Popular frameworks like Next.js strongly advocate for Typescript, further solidifying its position as the preferred choice for modern web development. This shift towards Typescript is a positive move towards a future where code is more understandable, easier to refactor, and less prone to runtime errors.

Why is typescript not enough?

We often like to think that Typescript solves all the problems inherent to Javascript, but unfortunately, that's not entirely true.

How many times do we not write an API call like this? I've done it thousands of times, and it seems to work, right?

async function getTodo(id: number): Promise<{ todo: Todo}> {
    const response = await fetch(`/todos/${id}`)
    const todo = await response.json()

    return { todo }
}

So, what's the problem here? At first glance, it looks straightforward and effective. However, several things could go wrong and as developers we need to take care of that. For error handling we can use try-catch.

async function getTodo(
  id: number
): Promise<
  | { ok: true; todo: any }
  | { ok: false; error: "InvalidJson" | "RequestFailed" }
> {
  try {
    const response = await fetch(`/todos/${id}`)
    if (!response.ok) throw new Error("Not OK!")
    try {
      const todo = await response.json()
      return { ok: true, todo }
    } catch (jsonError) {
      return { ok: false, error: "InvalidJson" }
    }
  } catch (error) {
    return { ok: false, error: "RequestFailed" }
  }
}

This is better but we had to add more then 10 lines of code for it and the nested try-catches can be hard to read.

But for a production-grade app, we might still need more features, like retries in case something fails. That would look something like this:

function getTodo(
  id: number
  {
    retries = 3,
    retryBaseDelay = 1000,
  }: { retries?: number; retryBaseDelay?: number },
): Promise<
  | { ok: true; todo: any }
  | { ok: false; error: "InvalidJson" | "RequestFailed" }
> {
  async function execute(
    attempt: number
  ): Promise<
    | { ok: true; todo: any }
    | { ok: false; error: "InvalidJson" | "RequestFailed" }
  > {
    try {
      const response = await fetch(`/todos/${id}`)
      if (!response.ok) throw new Error("Not OK!")
      try {
        const todo = await response.json()
        return { ok: true, todo }
      } catch (jsonError) {
        if (attempt < retries) {
          throw jsonError // jump to retry
        }
        return { ok: false, error: "InvalidJson" }
      }
    } catch (error) {
      if (attempt < retries) {
        const delayMs = retryBaseDelay * 2 ** attempt
        return new Promise((resolve) =>
          setTimeout(
            () => resolve(execute(attempt + 1)),
            delayMs,
          ),
        )
      }
      return { ok: false, error: "RequestFailed" }
    }
  }

  return execute(0)
}

The code is getting out of hand but we are still not done. Often we must introduce a mechanism for interruption to manage and clean up resources effectively. We can use the AbortSignal API for that

function getTodo(
  id: number
  {
    retries = 3,
    retryBaseDelay = 1000,
    signal,
  }: {
    retries?: number
    retryBaseDelay?: number
    signal?: AbortSignal
  },
): Promise<
  | { ok: true; todo: any }
  | {
      ok: false
      error: "InvalidJson" | "RequestFailed" | "Timeout"
    }
> {
  async function execute(attempt: number): Promise<
    | { ok: true; todo: any }
    | {
        ok: false
        error: "InvalidJson" | "RequestFailed" | "Timeout"
      }
  > {
    try {
      const controller = new AbortController()
      setTimeout(() => controller.abort(), 1000)
      signal?.addEventListener("abort", () =>
        controller.abort(),
      )
      const response = await fetch(`/todos/${id}`, {
        signal: controller.signal,
      })
      if (!response.ok) throw new Error("Not OK!")
      try {
        const todo = await response.json()
        return { ok: true, todo }
      } catch (jsonError) {
        if (attempt < retries) {
          throw jsonError // jump to retry
        }
        return { ok: false, error: "InvalidJson" }
      }
    } catch (error) {
      if ((error as Error).name === "AbortError") {
        return { ok: false, error: "Timeout" }
      } else if (attempt < retries) {
        const delayMs = retryBaseDelay * 2 ** attempt
        return new Promise((resolve) =>
          setTimeout(
            () => resolve(execute(attempt + 1)),
            delayMs,
          ),
        )
      }
      return { ok: false, error: "RequestFailed" }
    }
  }

  return execute(0)
}

Now our API is robustly designed, having addressed nearly all the typical issues. However, we find ourselves dealing with over 60 lines of code and the solution lacks modularity. This means we'd need to replicate this for each of our API routes, which is hardly efficient or scalable.

Additionally, another aspect worth considering is the incorporation of a tracer.

const tracer = Otel.trace.getTracer("todos")

function getTodo(
  id: number
  {
    retries = 3,
    retryBaseDelay = 1000,
    signal,
  }: {
    retries?: number
    retryBaseDelay?: number
    signal?: AbortSignal
  },
): Promise<
  | { ok: true; todo: any }
  | {
      ok: false
      error: "InvalidJson" | "RequestFailed" | "Timeout"
    }
> {
  return tracer.startActiveSpan(
    "getTodo",
    { attributes: { id } },
    async (span) => {
      try {
        const result = await execute(0)
        if (result.ok) {
          span.setStatus({ code: Otel.SpanStatusCode.OK })
        } else {
          span.setStatus({
            code: Otel.SpanStatusCode.ERROR,
            message: result.error,
          })
        }
        return result
      } finally {
        span.end()
      }
    },
  )

  async function execute(attempt: number): Promise<
    | { ok: true; todo: any }
    | {
        ok: false
        error: "InvalidJson" | "RequestFailed" | "Timeout"
      }
  > {
    try {
      const controller = new AbortController()
      setTimeout(() => controller.abort(), 1000)
      signal?.addEventListener("abort", () =>
        controller.abort(),
      )
      const response = await fetch(`/todos/${id}`, {
        signal: controller.signal,
      })
      if (!response.ok) throw new Error("Not OK!")
      try {
        const todo = await response.json()
        return { ok: true, todo }
      } catch (jsonError) {
        if (attempt < retries) {
          throw jsonError // jump to retry
        }
        return { ok: false, error: "InvalidJson" }
      }
    } catch (error) {
      if ((error as Error).name === "AbortError") {
        return { ok: false, error: "Timeout" }
      } else if (attempt < retries) {
        const delayMs = retryBaseDelay * 2 ** attempt
        return new Promise((resolve) =>
          setTimeout(
            () => resolve(execute(attempt + 1)),
            delayMs,
          ),
        )
      }
      return { ok: false, error: "RequestFailed" }
    }
  }
}

Now all of a sudden we have gone from from 6 lines of code to about 80 lines...

To be honest, I rarely go to these lengths when creating an API endpoint and that's largely due to how cumbersome it is.

Producing production-grade TypeScript is hard.

Challenges include:

No type-safety beyond the happy path
Error handling
Retrying on error
Interruptions
Observability
Schema validation

The last point, schema validation, isn't even covered in our code example, but we'd often turn to tools like Zod for this purpose.

What TypeScript lacks, that other languages offer, is a comprehensive standard library. Instead, we have NPM, which is great because we can find almost everything, but that comes with its own set of problems as well.

So, what should we do then?

Effect

Effect is designed to address the issues inherent in Typescript and to solve the challenges developers face when using it.

It does so using:

Powerful building blocks: Each component of the Effect ecosystem is crafted to be composable.
No more one-off deps:: With Effect, we have all we need, eliminating the necessity to depend on numerous npm packages. It provides tools for data validation and HTTP frameworks, among others.
No more try-catch:: Effect takes a comprehensive approach to error handling, ensuring all errors are type-safe and not just the happy path.

The 2022 State of JS survey highlighted a strong desire among developers for a standard library.

Effect can be utilized wherever Typescript is applicable, positioning itself as the missing standard library for Typescript. However, there's a catch:

Learning curve: Effect heavily relies on functional programming concepts, which can be intimidating for many developers.
Different programming style: The programming style of Effect is quite distinct from traditional Typescript, potentially making it challenging to adapt to.
Extensivve API: Aiming to be a standard library for Typescript, Effect boasts an API for nearly every situation, which can be overwhelming. Yet, mastering just a few of the most common ones can go a long way.

So, how would our production-grade code example look like in Effect?

const getTodo = (id: number): Effect.Effect<
  unknown,
  HttpClientError | TimeoutException
> =>
  Http.request.get(`/todos/${id}`).pipe(
    Http.client.fetchOk(),
    Http.response.json,
    Effect.timeout("1 seconds"),
    Effect.retry(
      Schedule.exponential(1000).pipe(
        Schedule.compose(Schedule.recurs(3)),
      ),
    ),
    Effect.withSpan("getTodo", { attributes: { id } }),
  )

This code is significantly shorter and more modular. Admittedly, it might be challenging to grasp what's happening if you're not familiar with the syntax, but it illustrates the power and potential of adopting Effect for Typescript development.

Conclusion

In this post we did not go into how to use or what effect really is. We talked about the problem it solves.

What does the future of Typescript look like, in your opinion?

Resources

This post is heavily inspired by the insightful talk from Johannes Schickling the founder of Primsa. You can watch his talk here

The effect website. Be sure to read the docs

Join the Discord: https://discord.gg/effect-ts

Learning resources:

DEV Community: Martin Persson

Building Reliable AI Agents with TypeScript and Effect.ts

The Agent Is the Easy Part

What We're Building

1. Don't Trust External Data

2. Model Failures Instead of Hiding Them

3. Context Is Part of the System

4. Expose a Small, Typed Tool

5. Test the Deterministic Parts

Where Effect Actually Helps

From Agent Demos to Software Factories

Stop Prompting AI. Start Engineering the Harness.

Your AI Doesn't Know Your Codebase

Context Is Infrastructure

1. Make Your Architecture Understandable

2. Turn Repeated Instructions Into Skills

3. Give AI Tools, Not Just Instructions

4. Build Security and Compliance Into the Architecture

5. Treat the Harness as an Internal Product

Building the Foundation for Software Factories

Stop Writing Software. Start Building Software Factories

Let's Talk About Henry Ford

We've Been Building Cars by Hand for 60 Years

I Love Writing Code. That's Becoming a Problem.

An AI Coding Assistant Is Not a Software Factory

So, How Do We Build One?

1. Give AI the right environment

2. Build specialized agents

3. Connect them into a production system

4. Build quality control into the factory

Developers Won't Disappear. Their Responsibilities Will Change.

Adapt or Get Left Behind

[Boost]

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

If you're building SaaS, learning how monorepos work or just want to see how modern TypeScript apps are structured. Orion Kit shows you the full stack: Next.js 15, Drizzle ORM, Stripe payments & JWT auth. Hope it's helpful!

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Links

What This Is

What’s Inside

Applications (4)

Shared Packages (9)

Technical Architecture

Type Safety Flow

Monorepo Structure

Integrated Features

Authentication

Payments

Database

Email

Testing

Observability & Analytics

Background Jobs

Development Workflow

Required Services (all have generous free tiers)

Getting Started

Prerequisites

1) Clone & install

2) Environment variables

3) Database

4) Dev servers

5) Tests

Documentation

Use Cases

Deployment (Overview)

Contributing

[Boost]

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

Building a Robust Backend with Effect, GraphQL, and Drizzle

Table of Contents

Introduction

The Problem

The Solution

1. Effect: Functional Effects for Robust Error Handling

2. Gradual Migration: Mix Effect and Promises

3. Branded Types: Type Safety That Actually Works

Architecture Overview

Domain Layer

Repository Layer