Lab: construir um subsistema

// notes/schema.ts

// Uma nota é uma string não-vazia, com trim, abaixo de 280 chars.
import { z } from 'zod';

export const noteSchema = z.string().trim().min(1).max(280);
export type Note = z.infer<typeof noteSchema>;

O pipeline inteiro do add(): validar, limitar, mutar, persistir — nessa ordem. Só o último passo toca o disco.

// notes/note-store.ts (topo)

import { ok, err, tryCatchAsync, type Result } from '@alembic/contracts';
import type { FsPort } from '@alembic/etl';
import { noteSchema } from './schema.js';

export const DEFAULT_MAX_NOTES = 50;
const FILENAME = 'NOTES.md';
const DELIMITER = '\n---\n';

export interface NoteOutcome {
  readonly message: string;
  readonly count: number;   // contagem viva após a escrita
  readonly max: number;
}

export class NoteStore {
  private entries: string[] = [];

  constructor(
    private readonly fs: FsPort,      // ← injetado. sem `import fs`.
    private readonly baseDir: string,
    private readonly max: number = DEFAULT_MAX_NOTES,
  ) {}

  private path(): string {
    return this.fs.joinPath(this.baseDir, FILENAME);
  }

Uma porta, dois fornecedores. A classe conhece só o shape de um filesystem — por isso o teste roda em memória.

  async load(): Promise<Result<void, Error>> {
    const ensured = await tryCatchAsync(() => this.fs.ensureDir(this.baseDir));
    if (!ensured.ok) return ensured;          // short-circuit em falha de IO

    const meta = await tryCatchAsync(() => this.fs.stat(this.path()));
    if (!meta.ok) return meta;
    if (!meta.value) { this.entries = []; return ok(undefined); }  // sem arquivo ⇒ vazio

    const read = await tryCatchAsync(() => this.fs.readText(this.path()));
    if (!read.ok) return read;
    this.entries = read.value.split(DELIMITER).map((s) => s.trim()).filter(Boolean);
    return ok(undefined);
  }

  async add(input: unknown): Promise<Result<NoteOutcome, Error>> {
    const parsed = noteSchema.safeParse(input);            // ① Zod de borda
    if (!parsed.success) return err(new Error(`Nota inválida: ${parsed.error.message}`));
    const note = parsed.data;

    if (this.entries.includes(note)) {                     // ② dedup (sucesso no-op)
      return ok({ message: 'exists', count: this.entries.length, max: this.max });
    }
    if (this.entries.length >= this.max) {                  // ③ limita ANTES de escrever
      return err(new Error(`Na capacidade (${this.max}). Remova uma nota antes.`));
    }

    this.entries.push(note);                                // ④ muta, depois persiste
    const saved = await tryCatchAsync(() =>
      this.fs.writeFileAtomic(this.path(), this.entries.join(DELIMITER)));
    if (!saved.ok) { this.entries.pop(); return saved; }   // rollback em falha de IO
    return ok({ message: 'added', count: this.entries.length, max: this.max });
  }

  list(): readonly string[] { return this.entries; }
}

A ordem das guardas, explorável

Clique em cada camada para ver o que ela faz — e por que está nessa posição:

// notes/note-store.test.ts — o fake tem ~10 linhas
const makeFakeFs = (): FsPort => {
  const store = new Map<string, string>();
  return {
    joinPath: (...p) => p.join('/'),
    stat: async (p) => (store.has(p) ? { size: 0, mtimeMs: 0, isFile: true, isDirectory: false } : undefined),
    readText: async (p) => store.get(p) ?? '',
    writeFileAtomic: async (p, c) => { store.set(p, c); },
    ensureDir: async () => {},
    // readDir / appendLine / openLineStream: não usados aqui — stub conforme precisar
  } as FsPort;
};

it('rejeita uma nota vazia e nunca lança', async () => {
  const s = new NoteStore(makeFakeFs(), '/x');
  expect((await s.add('   ')).ok).toBe(false);  // err, não um throw
});

Você escreveu cada camada que o motor exige. Agora estenda o store com uma operação nova — e cuide para que ela herde as mesmas quatro propriedades.

Um slide por ideia. Use as setas do teclado (← →) ou os botões para navegar.