03
Fundamentos y atributos de calidad

Modularidad: límites, acoplamiento y dependencias

Fundamentos y atributos de calidad

Semana 3 — Modularidad: límites, acoplamiento y dependencias

Objetivos

  • Explicar el criterio de Parnas para dividir un sistema en módulos (cada módulo esconde una decisión de diseño que puede cambiar) y aplicarlo a un caso.
  • Evaluar una división en módulos por su cohesión y su acoplamiento, y distinguir formas de acoplamiento más y menos dañinas.
  • Leer un grafo de dependencias, encontrar ciclos y explicar por qué impiden cambiar, probar y separar partes del sistema.
  • Invertir una dependencia con una interfaz (ports y adapters) y escribir reglas de dependencia que una herramienta comprueba en cada build.

Sesión A — Modularidad: ocultamiento de información, cohesión y acoplamiento

Lecturas:

Lecturas complementarias:

  • Richards y Ford, Fundamentals of Software Architecture (2.ª ed.), cap. 3 Modularity.
  • connascence.io: las formas de connascence, con ejemplos.
  • Software Architecture in Practice, cap. 15 Software Interfaces.

Temas:

  • Módulo: una unidad de código con una responsabilidad y una interfaz. La estructura de módulos responde qué toca un cambio y quién puede trabajar en paralelo; por eso la modularidad es la base de la modificabilidad.
  • Parnas (1972): el mismo programa (un índice KWIC) dividido de dos maneras. La primera sigue los pasos del procesamiento (leer, rotar, ordenar, imprimir) y todos los módulos conocen el formato de los datos; la segunda hace que cada módulo esconda una decisión (cómo se guardan las líneas, cómo se ordenan). Ambas funcionan; solo la segunda aguanta un cambio de formato sin tocar todo. El criterio: dividir por lo que puede cambiar, no por el orden en que se ejecuta.
  • Ocultamiento de información: la interfaz de un módulo es todo lo que los demás pueden suponer sobre él. Lo que no está en la interfaz se puede cambiar sin avisar. Un módulo que expone sus tablas, sus tipos internos o su orden de llamadas no esconde nada.
  • Cohesión: qué tan relacionadas están las cosas dentro de un módulo. Un módulo cohesivo tiene una razón para cambiar. Señales de baja cohesión: nombres como utils, common o manager; cambios que tocan solo una mitad del módulo.
  • Acoplamiento: cuánto debe saber un módulo de otro. No todo acoplamiento es igual: depender de una función pública estable es barato; depender del esquema de las tablas de otro módulo, de sus tipos internos o del orden en que hace las cosas es caro. Connascence da vocabulario para esto: de nombre, de tipo, de significado, de posición, de algoritmo, de tiempo; cuanto más fuerte y más lejos, peor.
  • La medida que importa: cuando llega un cambio probable, ¿cuántos módulos hay que tocar? La modificabilidad se escribe como escenario: “agregar un medio de pago toca un solo módulo y toma menos de dos días”.
  • En Tinkuy: reports lee archivos internos de orders y de catalog; el cobro tiene un if por medio de pago repartido en varios archivos. Cada uno es acoplamiento que se paga cuando llega el cambio.
  • Error común: creer que dividir en más módulos reduce el acoplamiento. Si dos módulos siempre cambian juntos, la división solo agregó una frontera que cruzar.
  • Error común: dividir por capa técnica (controllers, services, repositories) y concluir que el sistema es modular. Un cambio de negocio sigue tocando todas las carpetas.

Sesión B — Dependencias: ciclos, inversión de dependencias, ports y adapters

Lecturas:

Lecturas complementarias:

  • dependency-cruiser, Rules reference.
  • Fundamentals of Software Architecture (2.ª ed.), cap. 8 Component-Based Thinking.

Temas:

  • El grafo de dependencias: un nodo por módulo y una flecha de A a B si A importa algo de B. Es la estructura de módulos hecha visible, y se puede calcular a partir del código.
  • Ciclos: si A depende de B y B de A, ninguno se puede entender, probar, reutilizar ni desplegar sin el otro; en la práctica son un solo módulo con dos nombres. En Tinkuy, catalog y orders se importan mutuamente.
  • Dirección de las dependencias: lo que cambia mucho debe depender de lo que cambia poco, no al revés. Estabilidad: un módulo del que muchos dependen es caro de cambiar, así que conviene que sea el más abstracto.
  • Inversión de dependencias: el módulo de más alto nivel declara la interfaz que necesita y el de más bajo nivel la implementa. La dependencia en el código apunta hacia el núcleo aunque la llamada, al ejecutarse, vaya hacia afuera. Así se rompe un ciclo sin fusionar los módulos.
  • Ports y adapters (arquitectura hexagonal, Cockburn): el núcleo de la aplicación define ports, las interfaces que ofrece y las que necesita (PaymentGateway, Clock, SeatRepository); afuera, adapters los conectan con HTTP, PostgreSQL o la pasarela real. El núcleo no importa nada de afuera. Consecuencia práctica: se puede probar el núcleo sin base de datos y cambiar de pasarela escribiendo un adapter.
  • Dependency injection: quién crea el adapter y se lo pasa al núcleo. Basta con parámetros y un archivo que arma todo (el composition root); no hace falta un framework.
  • La interfaz pública de un módulo: un index.ts que exporta lo que los demás pueden usar. Todo lo demás es interno. La regla “un módulo solo importa a otro por su index.ts” convierte el ocultamiento de información en algo que se puede comprobar.
  • Reglas que se comprueban: una regla de arquitectura que solo vive en un documento se rompe en el primer apuro. dependency-cruiser lee los imports y falla el build si hay un ciclo, si http importa pg, o si alguien entra a un archivo interno. Es la primera fitness function del curso (semana 15).
  • Trade-off: cada interfaz es indirección que alguien tiene que leer. Un port con una sola implementación y sin pruebas que lo aprovechen es costo sin beneficio; se invierte donde hay un cambio probable o una frontera que se quiere proteger.
  • Error común: romper un ciclo moviendo el código compartido a un módulo shared del que todos dependen. El ciclo desaparece del grafo y el acoplamiento queda igual, ahora escondido.

Laboratorio — Reglas de dependencia con dependency-cruiser; romper un ciclo

Referencias: dependency-cruiser, Rules reference; Cockburn, Hexagonal Architecture. Material: code/week-03/. En parejas, sobre una copia de Tinkuy.

  1. En tinkuy/, correr make deps. Leer cada violación: qué regla, qué archivo importa a cuál. Clasificarlas por regla (no-circular, http-does-not-touch-db, modules-only-through-index).
  2. Abrir .dependency-cruiser.cjs y explicar cómo está escrita cada regla (from, to, path, pathNot). Generar el grafo de módulos como texto con el comando de code/week-03/ y compararlo con el que dibujaron a mano en la semana 1.
  3. Seguir el ciclo entre catalog y orders: qué necesita catalog de orders y qué necesita orders de catalog. Decidir cuál de las dos dependencias es la que no debería existir, y por qué.
  4. Romper el ciclo con una inversión de dependencias: el módulo que queda abajo declara una interfaz con lo que necesita, y el otro la implementa y se la pasa al armar la aplicación. Correr make deps (una violación menos) y make test (todo sigue pasando).
  5. Practicar con el ejemplo pequeño de code/week-03/: un núcleo con dos ports y adapters en memoria y de PostgreSQL. Escribir la prueba del núcleo que no necesita base de datos y medir cuánto tarda frente a la que sí la usa.
  6. Escribir una regla nueva en .dependency-cruiser.cjs: ningún archivo fuera de src/payments puede importar el cliente HTTP de la pasarela. Comprobar que falla si alguien la viola (hacer el import a propósito) y que pasa al quitarlo.
  7. Elegir una violación de modules-only-through-index y corregirla sin exportar todo desde el index.ts: decidir qué debe ser público. Anotar qué quedó expuesto y qué dejó de estarlo.

Entregas

Preguntas de repaso

  1. En el artículo de Parnas, ¿qué cambio obliga a modificar todos los módulos de la primera descomposición y uno solo de la segunda?
  2. Dos módulos comparten una tabla de la base de datos: uno escribe y el otro lee con su propio SQL. ¿Qué forma de acoplamiento es y qué cambio lo hace visible?
  3. ¿Por qué un ciclo entre dos módulos impide probar cada uno por separado? ¿Qué otra cosa impide?
  4. Dibujen, para la pasarela de pagos de Tinkuy, la dependencia antes y después de invertirla. ¿Hacia dónde apunta la flecha del import y hacia dónde va la llamada al ejecutarse?
  5. Den un caso en el que agregar un port no vale lo que cuesta.
  6. ¿Qué ventaja tiene una regla comprobada por una herramienta sobre la misma regla escrita en el README? ¿Qué no puede comprobar la herramienta?

Código de la semana

Compilar y probar dentro del contenedor del curso con make y make test.

Ejemplos (43)Errores (3)Pruebas (10)Laboratorio (1)Compilación (3)

Ejemplos

Los programas que usan los apuntes y la clase.

coupling/connascence.tsDescargar coupling/connascence.ts
// Tres formas de connascence entre quien define una función y quien la llama,
// de la más fuerte a la más débil, y el refactoring que baja de una a otra.
// El ejemplo es la multa por devolver tarde un libro.

// --- De posición: quien llama tiene que saber el orden de los argumentos.
// Los dos días son `string`: si se pasan al revés, compila igual.
export function lateFeeByPosition(dueOn: string, returnedOn: string, category: number): number {
  return lateFeeCents({ dueOn, returnedOn, category: category === 1 ? 'student' : 'visitor' });
}

// --- De significado: quien llama tiene que saber que 1 quiere decir
// estudiante y 2 visitante. Ese acuerdo no está escrito en ningún tipo.
export const STUDENT_CATEGORY = 1;
export const VISITOR_CATEGORY = 2;

// --- De nombre: quien llama solo tiene que conocer nombres (de la función,
// de los campos y de las categorías). Un cambio de nombre lo detecta tsc.
export type MemberCategory = 'student' | 'visitor';

const FEE_PER_DAY_CENTS: Record<MemberCategory, number> = { student: 50, visitor: 150 };

export function lateFeeCents(loan: { dueOn: string; returnedOn: string; category: MemberCategory }): number {
  const daysLate = Math.round((Date.parse(loan.returnedOn) - Date.parse(loan.dueOn)) / 86_400_000);
  return Math.max(0, daysLate) * FEE_PER_DAY_CENTS[loan.category];
}
kwic/change.tsDescargar kwic/change.ts
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { buildVariant, modulesOf, rewrittenFor, run, typeErrors, type Decomposition } from './variants.ts';

// El experimento de Parnas, hecho con las dos descomposiciones de esta
// carpeta: llega el cambio "las líneas se guardan de otra manera" y se cuenta
// cuántos módulos hay que tocar en cada una. Se corre con `make kwic-change`.

const titles = join(dirname(fileURLToPath(import.meta.url)), 'titles.txt');

// El primer paso del cambio: lo que reescribe quien es responsable de guardar
// las líneas.
const FIRST_STEP: Record<Decomposition, string[]> = {
  steps: ['formats.ts', 'input.ts'],
  decisions: ['line-storage.ts'],
};

function report(decomposition: Decomposition, title: string): void {
  const modules = modulesOf(decomposition);
  const rewritten = rewrittenFor(decomposition);
  const before = run(buildVariant(decomposition, `${decomposition}-before`, []), titles);

  console.log(`${title} (kwic/${decomposition}/, ${modules.length} archivos)`);
  console.log(`  1. Cambia la forma de guardar las líneas: ${FIRST_STEP[decomposition].join(', ')}`);

  const errors = typeErrors(buildVariant(decomposition, `${decomposition}-first-step`, FIRST_STEP[decomposition]));
  if (errors.size === 0) {
    console.log('  2. tsc: sin errores');
  } else {
    console.log('  2. tsc encuentra errores en otros módulos:');
    for (const [file, count] of [...errors].sort()) console.log(`       ${file}: ${count}`);
  }

  const after = run(buildVariant(decomposition, `${decomposition}-after`, rewritten), titles);
  console.log(`  3. Archivos reescritos para completar el cambio: ${rewritten.length} de ${modules.length} (${rewritten.join(', ')})`);
  console.log(`  4. El listado sale igual que antes: ${after === before ? 'sí' : 'NO'}`);
}

report('steps', 'Descomposición 1, por pasos');
console.log();
report('decisions', 'Descomposición 2, por decisiones');
kwic/titles.txtDescargar kwic/titles.txt
La ciudad y los perros
Los ríos profundos
El mundo es ancho y ajeno
kwic/variants.tsDescargar kwic/variants.ts
import { spawnSync } from 'node:child_process';
import { cpSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

// Arma copias de una descomposición con algunos de sus archivos reemplazados
// por los de kwic/change/, para ver qué pasa cuando cambia la forma de guardar
// las líneas. Las copias quedan en build/kwic/.

const here = dirname(fileURLToPath(import.meta.url));
const buildRoot = join(here, '..', 'build', 'kwic');

export type Decomposition = 'steps' | 'decisions';

/** Los archivos de una descomposición, en orden alfabético. */
export function modulesOf(decomposition: Decomposition): string[] {
  return readdirSync(join(here, decomposition)).sort();
}

/** Los archivos que hubo que reescribir para completar el cambio. */
export function rewrittenFor(decomposition: Decomposition): string[] {
  return readdirSync(join(here, 'change', decomposition)).sort();
}

/** Copia la descomposición a build/kwic/<name> y reemplaza `replaced` por su versión nueva. */
export function buildVariant(decomposition: Decomposition, name: string, replaced: string[]): string {
  const target = join(buildRoot, name);
  rmSync(target, { recursive: true, force: true });
  mkdirSync(target, { recursive: true });
  cpSync(join(here, decomposition), target, { recursive: true });
  for (const file of replaced) cpSync(join(here, 'change', decomposition, file), join(target, file));
  writeFileSync(join(target, 'tsconfig.json'), JSON.stringify({ extends: '../../../tsconfig.json', include: ['.'] }));
  return target;
}

/** Revisa los tipos de una copia y devuelve cuántos errores encontró tsc en cada archivo. */
export function typeErrors(variantDir: string): Map<string, number> {
  const result = spawnSync('tsc', ['-p', variantDir, '--pretty', 'false'], { encoding: 'utf8' });
  const errors = new Map<string, number>();
  for (const line of result.stdout.split('\n')) {
    const match = /([\w-]+\.ts)\(\d+,\d+\): error TS/.exec(line);
    if (match) errors.set(match[1]!, (errors.get(match[1]!) ?? 0) + 1);
  }
  return errors;
}

/** Corre el programa de una copia sobre un archivo de entrada y devuelve lo que escribe. */
export function run(variantDir: string, inputFile: string): string {
  const result = spawnSync('node', [join(variantDir, 'main.ts'), inputFile], { encoding: 'utf8' });
  if (result.status !== 0) throw new Error(result.stderr);
  return result.stdout;
}
library/scenario.tsDescargar library/scenario.ts
import type { LoanDesk } from './src/loans/index.ts';
import type { MemberDesk } from './src/members/index.ts';

/**
 * Una mañana en el mostrador: se inscribe un socio y, `rounds` veces, se lleva
 * un ejemplar, se consulta su carné y lo devuelve. Devuelve cuántos préstamos
 * se hicieron. Lo usan la comparación de tiempos y sus pruebas.
 */
export async function morningAtTheDesk(desks: { loanDesk: LoanDesk; memberDesk: MemberDesk }, rounds: number, tag: string): Promise<number> {
  const member = await desks.memberDesk.register(`Socio ${tag}`);
  let lent = 0;
  for (let round = 0; round < rounds; round++) {
    const copyCode = `${tag}-${round}`;
    await desks.loanDesk.lend(member, copyCode);
    const card = await desks.memberDesk.card(member.id);
    if (card.activeLoans !== 1) throw new Error(`El carné dice ${card.activeLoans} préstamos y debería decir 1`);
    await desks.loanDesk.giveBack(copyCode);
    lent++;
  }
  return lent;
}
library/schema.sqlDescargar library/schema.sql
-- La biblioteca del ejemplo: socios y préstamos de ejemplares.

CREATE TABLE members (
    id     integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name   text NOT NULL,
    status text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended'))
);

CREATE TABLE loans (
    id          integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    member_id   integer NOT NULL REFERENCES members (id),
    copy_code   text    NOT NULL,
    lent_on     date    NOT NULL,
    due_on      date    NOT NULL,
    returned_on date
);

-- Un ejemplar no puede estar prestado dos veces a la vez.
CREATE UNIQUE INDEX loans_one_active_per_copy ON loans (copy_code) WHERE returned_on IS NULL;
CREATE INDEX loans_active_by_member ON loans (member_id) WHERE returned_on IS NULL;
library/timing.tsDescargar library/timing.ts
import { performance } from 'node:perf_hooks';
import { createPool } from './src/adapters/postgres/pool.ts';
import { morningAtTheDesk } from './scenario.ts';
import { emptyTables, memoryLibrary, pgLibrary } from './wiring.ts';

// Compara cuánto tarda el mismo escenario con los adapters en memoria y con
// los de PostgreSQL. Se corre con `make timing` (ROUNDS=200 por omisión).

const rounds = Number(process.env.ROUNDS ?? 200);

async function measure(run: () => Promise<number>): Promise<number> {
  const start = performance.now();
  await run();
  return performance.now() - start;
}

const pool = createPool();
try {
  await emptyTables(pool);
  // Una vuelta de calentamiento con cada uno, que no se cuenta.
  await morningAtTheDesk(memoryLibrary(), 5, 'W');
  await morningAtTheDesk(pgLibrary(pool), 5, 'W');

  const memoryMs = await measure(() => morningAtTheDesk(memoryLibrary(), rounds, 'M'));
  const pgMs = await measure(() => morningAtTheDesk(pgLibrary(pool), rounds, 'P'));

  console.log(`${rounds} préstamos con consulta de carné y devolución`);
  console.log(`  adapters en memoria:     ${memoryMs.toFixed(1)} ms`);
  console.log(`  adapters de PostgreSQL:  ${pgMs.toFixed(1)} ms`);
  console.log(`  PostgreSQL tarda ${Math.round(pgMs / memoryMs)} veces más`);
} finally {
  await pool.end();
}
library/wiring.tsDescargar library/wiring.ts
import type pg from 'pg';
import { createFixedClock, type FixedClock } from './src/adapters/memory/fixed-clock.ts';
import { createMemoryLoanRepository } from './src/adapters/memory/memory-loan-repository.ts';
import { createMemoryMemberRepository } from './src/adapters/memory/memory-member-repository.ts';
import { createPgLoanRepository } from './src/adapters/postgres/pg-loan-repository.ts';
import { createPgMemberRepository } from './src/adapters/postgres/pg-member-repository.ts';
import { createLoanDesk, type LoanDesk } from './src/loans/index.ts';
import { createMemberDesk, type MemberDesk } from './src/members/index.ts';

// Dos maneras de armar el mismo núcleo, para las pruebas y la comparación de
// tiempos: con adapters en memoria y con adapters de PostgreSQL. El reloj es
// fijo en las dos, para que el resultado no dependa del día en que se corre.

export type Library = { loanDesk: LoanDesk; memberDesk: MemberDesk; clock: FixedClock };

export const START_DAY = '2026-03-02';

export function memoryLibrary(): Library {
  const clock = createFixedClock(START_DAY);
  const loanDesk = createLoanDesk({ loans: createMemoryLoanRepository(), clock });
  const memberDesk = createMemberDesk({ members: createMemoryMemberRepository(), activeLoans: loanDesk });
  return { loanDesk, memberDesk, clock };
}

export function pgLibrary(pool: pg.Pool): Library {
  const clock = createFixedClock(START_DAY);
  const loanDesk = createLoanDesk({ loans: createPgLoanRepository(pool), clock });
  const memberDesk = createMemberDesk({ members: createPgMemberRepository(pool), activeLoans: loanDesk });
  return { loanDesk, memberDesk, clock };
}

/** Deja las tablas vacías: cada prueba con PostgreSQL parte de cero. */
export async function emptyTables(pool: pg.Pool): Promise<void> {
  await pool.query('TRUNCATE loans, members RESTART IDENTITY');
}
kwic/decisions/alphabetizer.tsDescargar kwic/decisions/alphabetizer.ts
import type { CircularShifter } from './circular-shifter.ts';

// Esconde dos decisiones: qué significa "orden alfabético" (aquí, sin
// distinguir mayúsculas) y cuándo se ordena.

export interface Alphabetizer {
  /** El número de la rotación que queda en el lugar `position` del orden alfabético. */
  ith(position: number): number;
}

// La decisión escondida: se ordena todo una sola vez, la primera vez que
// alguien pregunta. Quien llama no puede saber cuándo ocurrió.
export function createAlphabetizer(shifter: CircularShifter): Alphabetizer {
  let order: number[] | undefined;

  function key(shift: number): string {
    const words: string[] = [];
    for (let i = 0; i < shifter.wordCount(shift); i++) words.push(shifter.word(shift, i));
    return words.join(' ').toLowerCase();
  }

  function sortAll(): number[] {
    const keyed = Array.from({ length: shifter.shiftCount() }, (_, shift) => ({ shift, key: key(shift) }));
    keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
    return keyed.map((entry) => entry.shift);
  }

  return {
    ith(position) {
      order ??= sortAll();
      const shift = order[position];
      if (shift === undefined) throw new RangeError(`No hay rotación en el lugar ${position}`);
      return shift;
    },
  };
}
kwic/decisions/circular-shifter.tsDescargar kwic/decisions/circular-shifter.ts
import type { LineStorage } from './line-storage.ts';

// Esconde cómo se obtienen las rotaciones. Hacia afuera se ve como otro
// almacén de líneas, que en vez de las líneas originales tiene todas sus
// rotaciones. La interfaz no promete ningún orden entre ellas.

export interface CircularShifter {
  /** Cuántas rotaciones hay en total. */
  shiftCount(): number;
  /** Cuántas palabras tiene la rotación `shift`. */
  wordCount(shift: number): number;
  /** La palabra número `index` de la rotación `shift`. */
  word(shift: number, index: number): string;
}

// La decisión escondida: no se guarda ninguna rotación. Se guarda un índice
// (línea, primera palabra) y cada palabra se calcula cuando se pide.
export function createCircularShifter(storage: LineStorage): CircularShifter {
  const index: { line: number; firstWord: number }[] = [];
  for (let line = 0; line < storage.lineCount(); line++) {
    for (let firstWord = 0; firstWord < storage.wordCount(line); firstWord++) {
      index.push({ line, firstWord });
    }
  }

  function entry(shift: number): { line: number; firstWord: number } {
    const found = index[shift];
    if (!found) throw new RangeError(`No existe la rotación ${shift}`);
    return found;
  }

  return {
    shiftCount: () => index.length,
    wordCount: (shift) => storage.wordCount(entry(shift).line),
    word(shift, position) {
      const { line, firstWord } = entry(shift);
      return storage.word(line, (firstWord + position) % storage.wordCount(line));
    },
  };
}
kwic/decisions/input.tsDescargar kwic/decisions/input.ts
import type { LineStorage } from './line-storage.ts';

// Esconde el formato de la entrada: un texto con una línea por renglón y las
// palabras separadas por espacios. Si mañana la entrada es un CSV, cambia solo
// este módulo.
export function readLines(text: string, storage: LineStorage): void {
  for (const raw of text.split('\n')) {
    const words = raw.split(/\s+/).filter((word) => word !== '');
    if (words.length > 0) storage.addLine(words);
  }
}
kwic/decisions/line-storage.tsDescargar kwic/decisions/line-storage.ts
// Descomposición 2 (cada módulo esconde una decisión). Este módulo esconde
// cómo se guardan las líneas en memoria. Los demás solo conocen la interfaz
// LineStorage.

export interface LineStorage {
  /** Guarda una línea nueva, formada por estas palabras, al final. */
  addLine(words: readonly string[]): void;
  /** Cuántas líneas hay guardadas. */
  lineCount(): number;
  /** Cuántas palabras tiene la línea `line` (la primera es la 0). */
  wordCount(line: number): number;
  /** La palabra número `index` de la línea `line`. */
  word(line: number, index: number): string;
}

// La decisión escondida: todos los caracteres en un solo texto, con un espacio
// entre palabra y palabra, y un índice con la posición donde empieza cada línea.
export function createLineStorage(): LineStorage {
  let chars = '';
  const lineStart: number[] = [];

  function lineText(line: number): string {
    if (line < 0 || line >= lineStart.length) throw new RangeError(`No existe la línea ${line}`);
    const to = line + 1 < lineStart.length ? lineStart[line + 1]! - 1 : chars.length;
    return chars.slice(lineStart[line]!, to);
  }

  return {
    addLine(words) {
      if (words.length === 0 || words.some((word) => word === '' || word.includes(' '))) {
        throw new RangeError('Una línea tiene al menos una palabra, y una palabra no tiene espacios');
      }
      if (chars !== '') chars += ' ';
      lineStart.push(chars.length);
      chars += words.join(' ');
    },
    lineCount: () => lineStart.length,
    wordCount: (line) => lineText(line).split(' ').length,
    word(line, index) {
      const word = lineText(line).split(' ')[index];
      if (word === undefined) throw new RangeError(`La línea ${line} no tiene palabra ${index}`);
      return word;
    },
  };
}
kwic/decisions/main.tsDescargar kwic/decisions/main.ts
import { readFileSync } from 'node:fs';
import { createAlphabetizer } from './alphabetizer.ts';
import { createCircularShifter } from './circular-shifter.ts';
import { readLines } from './input.ts';
import { createLineStorage } from './line-storage.ts';
import { render } from './output.ts';

// Control: arma los módulos y los pone a trabajar.
export function kwic(text: string): string {
  const storage = createLineStorage();
  readLines(text, storage);
  const shifter = createCircularShifter(storage);
  return render(shifter, createAlphabetizer(shifter));
}

if (import.meta.main) {
  process.stdout.write(kwic(readFileSync(process.argv[2] ?? 'kwic/titles.txt', 'utf8')));
}
kwic/decisions/output.tsDescargar kwic/decisions/output.ts
import type { Alphabetizer } from './alphabetizer.ts';
import type { CircularShifter } from './circular-shifter.ts';

// Esconde el formato del listado: una rotación por renglón.
export function render(shifter: CircularShifter, alphabetizer: Alphabetizer): string {
  let listing = '';
  for (let position = 0; position < shifter.shiftCount(); position++) {
    const shift = alphabetizer.ith(position);
    const words: string[] = [];
    for (let i = 0; i < shifter.wordCount(shift); i++) words.push(shifter.word(shift, i));
    listing += words.join(' ') + '\n';
  }
  return listing;
}
kwic/steps/alphabetize.tsDescargar kwic/steps/alphabetize.ts
import type { Lines, Shift } from './formats.ts';

// Módulo 3, orden alfabético: devuelve el mismo índice que recibe, ordenado.
// Para comparar dos rotaciones tiene que reconstruir su texto, así que conoce
// el formato de las líneas igual que quien lo escribió.
export function alphabetize(lines: Lines, shifts: Shift[]): Shift[] {
  return shifts
    .map((shift) => ({ shift, key: shiftText(lines, shift).toLowerCase() }))
    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
    .map((entry) => entry.shift);
}

function shiftText(lines: Lines, shift: Shift): string {
  const from = lines.lineStart[shift.line]!;
  const to = shift.line + 1 < lines.lineStart.length ? lines.lineStart[shift.line + 1]! - 1 : lines.chars.length;
  const tail = lines.chars.slice(shift.start, to);
  const head = lines.chars.slice(from, shift.start).trimEnd();
  return head === '' ? tail : `${tail} ${head}`;
}
kwic/steps/circular-shift.tsDescargar kwic/steps/circular-shift.ts
import type { Lines, Shift } from './formats.ts';

// Módulo 2, rotaciones: arma el índice de todas las rotaciones. No copia
// texto: anota dónde empieza cada una, y para eso recorre los caracteres.
export function circularShifts(lines: Lines): Shift[] {
  const shifts: Shift[] = [];
  for (let line = 0; line < lines.lineStart.length; line++) {
    const from = lines.lineStart[line]!;
    const to = line + 1 < lines.lineStart.length ? lines.lineStart[line + 1]! - 1 : lines.chars.length;
    // Una palabra empieza al inicio de la línea y después de cada espacio.
    for (let position = from; position < to; position++) {
      if (position === from || lines.chars[position - 1] === ' ') {
        shifts.push({ line, start: position });
      }
    }
  }
  return shifts;
}
kwic/steps/formats.tsDescargar kwic/steps/formats.ts
// Descomposición 1 (por pasos del procesamiento). Este archivo es el
// "documento de formatos" que Parnas dice que habría que escribir antes de
// repartir el trabajo: cómo quedan los datos en memoria. Los cuatro módulos lo
// conocen, y por eso es la interfaz entre ellos.

/**
 * Las líneas, tal como las deja el módulo de entrada: todos los caracteres en
 * un solo texto, una línea tras otra, con un espacio entre palabra y palabra
 * (también entre la última palabra de una línea y la primera de la siguiente).
 * `lineStart[i]` es la posición donde empieza la línea i.
 */
export type Lines = {
  chars: string;
  lineStart: number[];
};

/**
 * Una rotación: el número de la línea original y la posición, dentro de
 * `chars`, del primer carácter de la palabra con la que empieza.
 */
export type Shift = {
  line: number;
  start: number;
};
kwic/steps/input.tsDescargar kwic/steps/input.ts
import type { Lines } from './formats.ts';

// Módulo 1, entrada: lee las líneas y las deja en memoria con el formato de
// formats.ts.
export function readLines(text: string): Lines {
  const lines: Lines = { chars: '', lineStart: [] };
  for (const raw of text.split('\n')) {
    const words = raw.split(/\s+/).filter((word) => word !== '');
    if (words.length === 0) continue;
    if (lines.chars !== '') lines.chars += ' ';
    lines.lineStart.push(lines.chars.length);
    lines.chars += words.join(' ');
  }
  return lines;
}
kwic/steps/main.tsDescargar kwic/steps/main.ts
import { readFileSync } from 'node:fs';
import { alphabetize } from './alphabetize.ts';
import { circularShifts } from './circular-shift.ts';
import { readLines } from './input.ts';
import { render } from './output.ts';

// Módulo 5, control: llama a los otros cuatro en orden. Es el diagrama de
// flujo del programa.
export function kwic(text: string): string {
  const lines = readLines(text);
  const shifts = circularShifts(lines);
  const sorted = alphabetize(lines, shifts);
  return render(lines, sorted);
}

if (import.meta.main) {
  process.stdout.write(kwic(readFileSync(process.argv[2] ?? 'kwic/titles.txt', 'utf8')));
}
kwic/steps/output.tsDescargar kwic/steps/output.ts
import type { Lines, Shift } from './formats.ts';

// Módulo 4, salida: escribe las rotaciones en el orden del índice que recibe.
// Vuelve a reconstruir el texto de cada rotación: la misma cuenta que hace el
// módulo 3, escrita otra vez.
export function render(lines: Lines, sorted: Shift[]): string {
  let listing = '';
  for (const shift of sorted) {
    const from = lines.lineStart[shift.line]!;
    const to = shift.line + 1 < lines.lineStart.length ? lines.lineStart[shift.line + 1]! - 1 : lines.chars.length;
    const tail = lines.chars.slice(shift.start, to);
    const head = lines.chars.slice(from, shift.start).trimEnd();
    listing += (head === '' ? tail : `${tail} ${head}`) + '\n';
  }
  return listing;
}
library/src/main.tsDescargar library/src/main.ts
import { createFixedClock } from './adapters/memory/fixed-clock.ts';
import { createMemoryLoanRepository } from './adapters/memory/memory-loan-repository.ts';
import { createMemoryMemberRepository } from './adapters/memory/memory-member-repository.ts';
import { createPgLoanRepository } from './adapters/postgres/pg-loan-repository.ts';
import { createPgMemberRepository } from './adapters/postgres/pg-member-repository.ts';
import { createPool } from './adapters/postgres/pool.ts';
import { systemClock } from './adapters/system-clock.ts';
import { createLoanDesk, LoanError, type Clock, type LoanRepository } from './loans/index.ts';
import { createMemberDesk, type MemberRepository } from './members/index.ts';

// El composition root: el único archivo que conoce a todos. Elige los
// adapters, arma los módulos y les pasa lo que necesitan. Aquí no hay reglas
// del negocio.
//
//   node src/main.ts            con PostgreSQL y el reloj de la computadora
//   node src/main.ts --memory   todo en memoria, con el reloj en un día fijo

type Adapters = {
  loans: LoanRepository;
  members: MemberRepository;
  clock: Clock;
  close(): Promise<void>;
};

function chooseAdapters(inMemory: boolean): Adapters {
  if (inMemory) {
    return {
      loans: createMemoryLoanRepository(),
      members: createMemoryMemberRepository(),
      clock: createFixedClock('2026-03-02'),
      close: async () => {},
    };
  }
  const pool = createPool();
  return {
    loans: createPgLoanRepository(pool),
    members: createPgMemberRepository(pool),
    clock: systemClock,
    close: () => pool.end(),
  };
}

const adapters = chooseAdapters(process.argv.includes('--memory'));
try {
  const loanDesk = createLoanDesk({ loans: adapters.loans, clock: adapters.clock });
  // loanDesk sabe contar préstamos: cumple el port ActiveLoanCounter de members.
  const memberDesk = createMemberDesk({ members: adapters.members, activeLoans: loanDesk });

  const rosa = await memberDesk.register('Rosa Quispe');
  const suffix = `${rosa.id}`.padStart(3, '0');
  for (const copyCode of [`YAW-${suffix}`, `RIO-${suffix}`]) {
    const loan = await loanDesk.lend(rosa, copyCode);
    console.log(`Prestado ${loan.copyCode} a ${rosa.name} hasta el ${loan.dueOn}`);
  }
  try {
    await loanDesk.lend(rosa, `YAW-${suffix}`);
  } catch (error) {
    if (!(error instanceof LoanError)) throw error;
    console.log(`Rechazado (${error.code}): ${error.message}`);
  }
  const card = await memberDesk.card(rosa.id);
  console.log(`Carné de ${card.member.name}: ${card.activeLoans} libros en su poder`);
} finally {
  await adapters.close();
}
kwic/change/decisions/line-storage.tsDescargar kwic/change/decisions/line-storage.ts
// Descomposición 2 después del cambio. La interfaz es la misma, letra por
// letra; lo que cambió es la decisión escondida: ahora cada línea se guarda
// como una lista de palabras.

export interface LineStorage {
  /** Guarda una línea nueva, formada por estas palabras, al final. */
  addLine(words: readonly string[]): void;
  /** Cuántas líneas hay guardadas. */
  lineCount(): number;
  /** Cuántas palabras tiene la línea `line` (la primera es la 0). */
  wordCount(line: number): number;
  /** La palabra número `index` de la línea `line`. */
  word(line: number, index: number): string;
}

export function createLineStorage(): LineStorage {
  const lines: string[][] = [];

  function wordsOf(line: number): string[] {
    const words = lines[line];
    if (!words) throw new RangeError(`No existe la línea ${line}`);
    return words;
  }

  return {
    addLine(words) {
      if (words.length === 0 || words.some((word) => word === '' || word.includes(' '))) {
        throw new RangeError('Una línea tiene al menos una palabra, y una palabra no tiene espacios');
      }
      lines.push([...words]);
    },
    lineCount: () => lines.length,
    wordCount: (line) => wordsOf(line).length,
    word(line, index) {
      const word = wordsOf(line)[index];
      if (word === undefined) throw new RangeError(`La línea ${line} no tiene palabra ${index}`);
      return word;
    },
  };
}
kwic/change/steps/alphabetize.tsDescargar kwic/change/steps/alphabetize.ts
import type { Lines, Shift } from './formats.ts';

// Módulo 3, orden alfabético, con el formato nuevo.
export function alphabetize(lines: Lines, shifts: Shift[]): Shift[] {
  return shifts
    .map((shift) => ({ shift, key: shiftText(lines, shift).toLowerCase() }))
    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
    .map((entry) => entry.shift);
}

function shiftText(lines: Lines, shift: Shift): string {
  const words = lines.words[shift.line]!;
  return [...words.slice(shift.firstWord), ...words.slice(0, shift.firstWord)].join(' ');
}
kwic/change/steps/circular-shift.tsDescargar kwic/change/steps/circular-shift.ts
import type { Lines, Shift } from './formats.ts';

// Módulo 2, rotaciones, con el formato nuevo: ya no busca espacios, cuenta
// palabras.
export function circularShifts(lines: Lines): Shift[] {
  const shifts: Shift[] = [];
  for (let line = 0; line < lines.words.length; line++) {
    for (let firstWord = 0; firstWord < lines.words[line]!.length; firstWord++) {
      shifts.push({ line, firstWord });
    }
  }
  return shifts;
}
kwic/change/steps/formats.tsDescargar kwic/change/steps/formats.ts
// Descomposición 1 después del cambio: las líneas ya no se guardan en un solo
// texto, sino como una lista de palabras por línea.

/** Las líneas, tal como las deja el módulo de entrada: `words[i]` son las palabras de la línea i. */
export type Lines = {
  words: string[][];
};

/** Una rotación: el número de la línea original y el índice de la palabra con la que empieza. */
export type Shift = {
  line: number;
  firstWord: number;
};
kwic/change/steps/input.tsDescargar kwic/change/steps/input.ts
import type { Lines } from './formats.ts';

// Módulo 1, entrada, con el formato nuevo.
export function readLines(text: string): Lines {
  const lines: Lines = { words: [] };
  for (const raw of text.split('\n')) {
    const words = raw.split(/\s+/).filter((word) => word !== '');
    if (words.length > 0) lines.words.push(words);
  }
  return lines;
}
kwic/change/steps/output.tsDescargar kwic/change/steps/output.ts
import type { Lines, Shift } from './formats.ts';

// Módulo 4, salida, con el formato nuevo.
export function render(lines: Lines, sorted: Shift[]): string {
  let listing = '';
  for (const shift of sorted) {
    const words = lines.words[shift.line]!;
    listing += [...words.slice(shift.firstWord), ...words.slice(0, shift.firstWord)].join(' ') + '\n';
  }
  return listing;
}
library/src/adapters/system-clock.tsDescargar library/src/adapters/system-clock.ts
import type { Clock } from '../loans/index.ts';

/** El reloj de verdad: el día de hoy según la computadora, en UTC. */
export const systemClock: Clock = {
  today: () => new Date().toISOString().slice(0, 10),
};
library/src/loans/index.tsDescargar library/src/loans/index.ts
// Préstamos: prestar y devolver ejemplares. Esto es lo que los demás módulos
// pueden usar; la política (policy.ts) queda adentro.

export { createLoanDesk } from './loan-desk.ts';
export type { LoanDesk } from './loan-desk.ts';
export type { Clock, LoanRepository } from './ports.ts';
export { LoanError } from './types.ts';
export type { Day, Loan, LoanErrorCode, NewLoan } from './types.ts';
library/src/loans/loan-desk.tsDescargar library/src/loans/loan-desk.ts
import type { Member } from '../members/index.ts';
import { dueDay, MAX_ACTIVE_LOANS } from './policy.ts';
import type { Clock, LoanRepository } from './ports.ts';
import { LoanError, type Loan } from './types.ts';

// El núcleo: las reglas para prestar y devolver. No sabe dónde se guardan los
// préstamos ni de dónde sale la fecha; eso llega por los dos ports.

export type LoanDesk = {
  lend(member: Member, copyCode: string): Promise<Loan>;
  giveBack(copyCode: string): Promise<Loan>;
  countActiveLoans(memberId: number): Promise<number>;
};

export function createLoanDesk(deps: { loans: LoanRepository; clock: Clock }): LoanDesk {
  return {
    async lend(member, copyCode) {
      if (member.status !== 'active') {
        throw new LoanError('MEMBER_SUSPENDED', `${member.name} tiene el carné suspendido`);
      }
      if (await deps.loans.activeByCopy(copyCode)) {
        throw new LoanError('COPY_ON_LOAN', `El ejemplar ${copyCode} ya está prestado`);
      }

      const today = deps.clock.today();
      const current = await deps.loans.activeByMember(member.id);
      if (current.some((loan) => loan.dueOn < today)) {
        throw new LoanError('HAS_OVERDUE', `${member.name} tiene préstamos vencidos`);
      }
      if (current.length >= MAX_ACTIVE_LOANS) {
        throw new LoanError('LOAN_LIMIT', `${member.name} ya tiene ${MAX_ACTIVE_LOANS} libros en su poder`);
      }

      return deps.loans.add({ memberId: member.id, copyCode, lentOn: today, dueOn: dueDay(today) });
    },

    async giveBack(copyCode) {
      const loan = await deps.loans.activeByCopy(copyCode);
      if (!loan) throw new LoanError('NOT_ON_LOAN', `El ejemplar ${copyCode} no está prestado`);
      const returnedOn = deps.clock.today();
      await deps.loans.markReturned(loan.id, returnedOn);
      return { ...loan, returnedOn };
    },

    async countActiveLoans(memberId) {
      return (await deps.loans.activeByMember(memberId)).length;
    },
  };
}
library/src/loans/policy.tsDescargar library/src/loans/policy.ts
import type { Day } from './types.ts';

// La política de préstamos. Es interna del módulo: si mañana el plazo depende
// del tipo de socio, nadie de afuera debería enterarse.

export const LOAN_DAYS = 14;
export const MAX_ACTIVE_LOANS = 3;

/** El día en que vence un préstamo hecho el día `lentOn`. */
export function dueDay(lentOn: Day): Day {
  const date = new Date(`${lentOn}T00:00:00Z`);
  date.setUTCDate(date.getUTCDate() + LOAN_DAYS);
  return date.toISOString().slice(0, 10);
}
library/src/loans/ports.tsDescargar library/src/loans/ports.ts
import type { Day, Loan, NewLoan } from './types.ts';

// Los dos ports del núcleo de préstamos. El núcleo los declara; los adapters
// de src/adapters/ los implementan.

/** Dónde se guardan los préstamos. */
export interface LoanRepository {
  add(loan: NewLoan): Promise<Loan>;
  /** El préstamo vigente de un ejemplar, si está prestado. */
  activeByCopy(copyCode: string): Promise<Loan | undefined>;
  /** Los préstamos vigentes de un socio, del más antiguo al más reciente. */
  activeByMember(memberId: number): Promise<Loan[]>;
  markReturned(loanId: number, returnedOn: Day): Promise<void>;
}

/** Qué día es hoy. */
export interface Clock {
  today(): Day;
}
library/src/loans/types.tsDescargar library/src/loans/types.ts
/** Un día del calendario, como texto `AAAA-MM-DD`. Se compara con < y >. */
export type Day = string;

/** Un préstamo: un ejemplar (por su código) en manos de un socio. */
export type Loan = {
  id: number;
  memberId: number;
  copyCode: string;
  lentOn: Day;
  dueOn: Day;
  returnedOn: Day | null;
};

export type NewLoan = Omit<Loan, 'id' | 'returnedOn'>;

export type LoanErrorCode = 'MEMBER_SUSPENDED' | 'COPY_ON_LOAN' | 'HAS_OVERDUE' | 'LOAN_LIMIT' | 'NOT_ON_LOAN';

/** Un préstamo o una devolución que las reglas de la biblioteca no permiten. */
export class LoanError extends Error {
  readonly code: LoanErrorCode;

  constructor(code: LoanErrorCode, message: string) {
    super(message);
    this.name = 'LoanError';
    this.code = code;
  }
}
library/src/members/index.tsDescargar library/src/members/index.ts
// Socios: quién puede usar la biblioteca. Esto es lo que los demás módulos
// pueden usar; el resto de la carpeta es interno.

export { createMemberDesk, MemberNotFound } from './member-desk.ts';
export type { MemberDesk } from './member-desk.ts';
export type { ActiveLoanCounter, MemberRepository } from './ports.ts';
export type { Member, MemberCard, MemberStatus } from './types.ts';
library/src/members/member-desk.tsDescargar library/src/members/member-desk.ts
import type { ActiveLoanCounter, MemberRepository } from './ports.ts';
import type { Member, MemberCard } from './types.ts';

export class MemberNotFound extends Error {
  constructor(memberId: number) {
    super(`No existe el socio ${memberId}`);
    this.name = 'MemberNotFound';
  }
}

export type MemberDesk = {
  register(name: string): Promise<Member>;
  find(memberId: number): Promise<Member>;
  suspend(memberId: number): Promise<void>;
  card(memberId: number): Promise<MemberCard>;
};

export function createMemberDesk(deps: { members: MemberRepository; activeLoans: ActiveLoanCounter }): MemberDesk {
  async function find(memberId: number): Promise<Member> {
    const member = await deps.members.find(memberId);
    if (!member) throw new MemberNotFound(memberId);
    return member;
  }

  return {
    register: (name) => deps.members.add(name.trim()),
    find,
    async suspend(memberId) {
      await find(memberId);
      await deps.members.setStatus(memberId, 'suspended');
    },
    async card(memberId) {
      const member = await find(memberId);
      return { member, activeLoans: await deps.activeLoans.countActiveLoans(memberId) };
    },
  };
}
library/src/members/ports.tsDescargar library/src/members/ports.ts
import type { Member, MemberStatus } from './types.ts';

// Los ports del módulo de socios: lo que necesita de afuera, dicho en sus
// propios términos.

/** Dónde se guardan los socios. */
export interface MemberRepository {
  add(name: string): Promise<Member>;
  find(memberId: number): Promise<Member | undefined>;
  setStatus(memberId: number, status: MemberStatus): Promise<void>;
}

/**
 * Lo único que el carné necesita saber de los préstamos. Lo declara este
 * módulo y lo implementa quien sepa contar préstamos: así members no importa
 * nada de loans.
 */
export interface ActiveLoanCounter {
  countActiveLoans(memberId: number): Promise<number>;
}
library/src/members/types.tsDescargar library/src/members/types.ts
export type MemberStatus = 'active' | 'suspended';

/** Un socio de la biblioteca. */
export type Member = {
  id: number;
  name: string;
  status: MemberStatus;
};

/** El carné que se muestra en el mostrador: el socio y cuántos libros tiene en su poder. */
export type MemberCard = {
  member: Member;
  activeLoans: number;
};
library/src/adapters/memory/fixed-clock.tsDescargar library/src/adapters/memory/fixed-clock.ts
import type { Clock, Day } from '../../loans/index.ts';

/** Un reloj que marca el día que se le diga: las pruebas deciden qué día es hoy. */
export type FixedClock = Clock & { set(day: Day): void };

export function createFixedClock(day: Day): FixedClock {
  let current = day;
  return {
    today: () => current,
    set(next) {
      current = next;
    },
  };
}
library/src/adapters/memory/memory-loan-repository.tsDescargar library/src/adapters/memory/memory-loan-repository.ts
import type { Loan, LoanRepository } from '../../loans/index.ts';

// Adapter en memoria del port LoanRepository: una lista. Sirve para las
// pruebas del núcleo y para correr el sistema sin base de datos.
export function createMemoryLoanRepository(): LoanRepository {
  const loans: Loan[] = [];

  return {
    async add(loan) {
      const saved: Loan = { ...loan, id: loans.length + 1, returnedOn: null };
      loans.push(saved);
      return { ...saved };
    },
    async activeByCopy(copyCode) {
      const found = loans.find((loan) => loan.copyCode === copyCode && loan.returnedOn === null);
      return found && { ...found };
    },
    async activeByMember(memberId) {
      return loans.filter((loan) => loan.memberId === memberId && loan.returnedOn === null).map((loan) => ({ ...loan }));
    },
    async markReturned(loanId, returnedOn) {
      const loan = loans.find((candidate) => candidate.id === loanId);
      if (loan) loan.returnedOn = returnedOn;
    },
  };
}
library/src/adapters/memory/memory-member-repository.tsDescargar library/src/adapters/memory/memory-member-repository.ts
import type { Member, MemberRepository } from '../../members/index.ts';

// Adapter en memoria del port MemberRepository.
export function createMemoryMemberRepository(): MemberRepository {
  const members: Member[] = [];

  return {
    async add(name) {
      const member: Member = { id: members.length + 1, name, status: 'active' };
      members.push(member);
      return { ...member };
    },
    async find(memberId) {
      const found = members.find((member) => member.id === memberId);
      return found && { ...found };
    },
    async setStatus(memberId, status) {
      const member = members.find((candidate) => candidate.id === memberId);
      if (member) member.status = status;
    },
  };
}
library/src/adapters/postgres/pg-loan-repository.tsDescargar library/src/adapters/postgres/pg-loan-repository.ts
import type pg from 'pg';
import type { Loan, LoanRepository } from '../../loans/index.ts';

// Adapter de PostgreSQL del port LoanRepository: traduce cada operación a SQL
// y cada fila a un Loan. Todo lo que se sabe de la tabla loans está aquí.

type LoanRow = {
  id: number;
  member_id: number;
  copy_code: string;
  lent_on: string;
  due_on: string;
  returned_on: string | null;
};

// Las fechas salen como texto AAAA-MM-DD, que es como las entiende el núcleo.
const COLUMNS = 'id, member_id, copy_code, lent_on::text, due_on::text, returned_on::text';

function toLoan(row: LoanRow): Loan {
  return {
    id: row.id,
    memberId: row.member_id,
    copyCode: row.copy_code,
    lentOn: row.lent_on,
    dueOn: row.due_on,
    returnedOn: row.returned_on,
  };
}

export function createPgLoanRepository(pool: pg.Pool): LoanRepository {
  return {
    async add(loan) {
      const result = await pool.query<LoanRow>(
        `INSERT INTO loans (member_id, copy_code, lent_on, due_on) VALUES ($1, $2, $3, $4) RETURNING ${COLUMNS}`,
        [loan.memberId, loan.copyCode, loan.lentOn, loan.dueOn],
      );
      return toLoan(result.rows[0]!);
    },
    async activeByCopy(copyCode) {
      const result = await pool.query<LoanRow>(
        `SELECT ${COLUMNS} FROM loans WHERE copy_code = $1 AND returned_on IS NULL`,
        [copyCode],
      );
      return result.rows[0] && toLoan(result.rows[0]);
    },
    async activeByMember(memberId) {
      const result = await pool.query<LoanRow>(
        `SELECT ${COLUMNS} FROM loans WHERE member_id = $1 AND returned_on IS NULL ORDER BY id`,
        [memberId],
      );
      return result.rows.map(toLoan);
    },
    async markReturned(loanId, returnedOn) {
      await pool.query('UPDATE loans SET returned_on = $2 WHERE id = $1', [loanId, returnedOn]);
    },
  };
}
library/src/adapters/postgres/pg-member-repository.tsDescargar library/src/adapters/postgres/pg-member-repository.ts
import type pg from 'pg';
import type { Member, MemberRepository } from '../../members/index.ts';

// Adapter de PostgreSQL del port MemberRepository.
export function createPgMemberRepository(pool: pg.Pool): MemberRepository {
  return {
    async add(name) {
      const result = await pool.query<Member>('INSERT INTO members (name) VALUES ($1) RETURNING id, name, status', [name]);
      return result.rows[0]!;
    },
    async find(memberId) {
      const result = await pool.query<Member>('SELECT id, name, status FROM members WHERE id = $1', [memberId]);
      return result.rows[0];
    },
    async setStatus(memberId, status) {
      await pool.query('UPDATE members SET status = $2 WHERE id = $1', [memberId, status]);
    },
  };
}
library/src/adapters/postgres/pool.tsDescargar library/src/adapters/postgres/pool.ts
import pg from 'pg';

/** Las conexiones a la base de datos del ejemplo. Quien la crea la cierra con `pool.end()`. */
export function createPool(database = process.env.LIBRARY_DB ?? 'arq_w03'): pg.Pool {
  return new pg.Pool({ database, max: 4 });
}

Errores

Ejemplos con errores a propósito: no compilan, fallan o dan un resultado incorrecto. Los apuntes explican cada uno.

errors/cycle/src/members/member-desk.tsDescargar errors/cycle/src/members/member-desk.ts
// ERROR A PROPÓSITO (regla no-circular). Esta es la versión del módulo de
// socios antes de invertir la dependencia: para armar el carné le pide la
// cuenta al mostrador de préstamos, así que importa su tipo. Pero loans ya
// importaba a members (el tipo Member): cada módulo necesita al otro.
import type { LoanDesk } from '../loans/index.ts';
import type { MemberRepository } from './ports.ts';
import type { Member, MemberCard } from './types.ts';

export class MemberNotFound extends Error {
  constructor(memberId: number) {
    super(`No existe el socio ${memberId}`);
    this.name = 'MemberNotFound';
  }
}

export type MemberDesk = {
  register(name: string): Promise<Member>;
  find(memberId: number): Promise<Member>;
  suspend(memberId: number): Promise<void>;
  card(memberId: number): Promise<MemberCard>;
};

export function createMemberDesk(deps: { members: MemberRepository; activeLoans: LoanDesk }): MemberDesk {
  async function find(memberId: number): Promise<Member> {
    const member = await deps.members.find(memberId);
    if (!member) throw new MemberNotFound(memberId);
    return member;
  }

  return {
    register: (name) => deps.members.add(name.trim()),
    find,
    async suspend(memberId) {
      await find(memberId);
      await deps.members.setStatus(memberId, 'suspended');
    },
    async card(memberId) {
      const member = await find(memberId);
      return { member, activeLoans: await deps.activeLoans.countActiveLoans(memberId) };
    },
  };
}
errors/deep-import/src/adapters/overdue-notice.tsDescargar errors/deep-import/src/adapters/overdue-notice.ts
// ERROR A PROPÓSITO (regla modules-only-through-index). Un adapter nuevo que
// redacta el aviso de vencimiento. Necesitaba el plazo del préstamo y lo
// importó de donde estaba: un archivo interno de loans. Desde ese día, la
// política de préstamos ya no se puede reorganizar sin romper este archivo.
import type { Loan } from '../loans/index.ts';
import { LOAN_DAYS } from '../loans/policy.ts';

export function overdueNotice(loan: Loan, memberName: string): string {
  return `${memberName}: el ejemplar ${loan.copyCode} venció el ${loan.dueOn}. El plazo de préstamo es de ${LOAN_DAYS} días.`;
}
errors/driver-in-core/src/loans/loan-desk.tsDescargar errors/driver-in-core/src/loans/loan-desk.ts
// ERROR A PROPÓSITO (regla core-does-not-touch-infrastructure). Alguien
// necesitaba contar los préstamos de un socio "rápido" y escribió la consulta
// aquí mismo. Funciona, y desde ese día el núcleo no se puede probar sin una
// base de datos ni cambiar de tabla sin tocar las reglas del negocio.
import pg from 'pg';
import type { Member } from '../members/index.ts';
import { dueDay, MAX_ACTIVE_LOANS } from './policy.ts';
import type { Clock, LoanRepository } from './ports.ts';
import { LoanError, type Loan } from './types.ts';

export type LoanDesk = {
  lend(member: Member, copyCode: string): Promise<Loan>;
  giveBack(copyCode: string): Promise<Loan>;
  countActiveLoans(memberId: number): Promise<number>;
};

const pool = new pg.Pool({ database: process.env.LIBRARY_DB ?? 'arq_w03', max: 1 });

export function createLoanDesk(deps: { loans: LoanRepository; clock: Clock }): LoanDesk {
  return {
    async lend(member, copyCode) {
      if (member.status !== 'active') {
        throw new LoanError('MEMBER_SUSPENDED', `${member.name} tiene el carné suspendido`);
      }
      if (await deps.loans.activeByCopy(copyCode)) {
        throw new LoanError('COPY_ON_LOAN', `El ejemplar ${copyCode} ya está prestado`);
      }

      const today = deps.clock.today();
      const current = await deps.loans.activeByMember(member.id);
      if (current.some((loan) => loan.dueOn < today)) {
        throw new LoanError('HAS_OVERDUE', `${member.name} tiene préstamos vencidos`);
      }
      if (current.length >= MAX_ACTIVE_LOANS) {
        throw new LoanError('LOAN_LIMIT', `${member.name} ya tiene ${MAX_ACTIVE_LOANS} libros en su poder`);
      }

      return deps.loans.add({ memberId: member.id, copyCode, lentOn: today, dueOn: dueDay(today) });
    },

    async giveBack(copyCode) {
      const loan = await deps.loans.activeByCopy(copyCode);
      if (!loan) throw new LoanError('NOT_ON_LOAN', `El ejemplar ${copyCode} no está prestado`);
      const returnedOn = deps.clock.today();
      await deps.loans.markReturned(loan.id, returnedOn);
      return { ...loan, returnedOn };
    },

    // El atajo: el núcleo le habla a la tabla directamente.
    async countActiveLoans(memberId) {
      const result = await pool.query<{ total: number }>(
        'SELECT count(*)::int AS total FROM loans WHERE member_id = $1 AND returned_on IS NULL',
        [memberId],
      );
      return result.rows[0]!.total;
    },
  };
}

Pruebas

Comprueban lo que afirman los apuntes; se ejecutan con make test.

coupling/connascence.test.tsDescargar coupling/connascence.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { lateFeeByPosition, lateFeeCents } from './connascence.ts';

test('con campos con nombre, la multa es por día de atraso y según la categoría', () => {
  assert.equal(lateFeeCents({ dueOn: '2026-03-16', returnedOn: '2026-03-20', category: 'student' }), 200);
  assert.equal(lateFeeCents({ dueOn: '2026-03-16', returnedOn: '2026-03-20', category: 'visitor' }), 600);
  assert.equal(lateFeeCents({ dueOn: '2026-03-16', returnedOn: '2026-03-16', category: 'visitor' }), 0);
});

test('connascence de posición: con los dos días al revés compila igual y la multa desaparece', () => {
  assert.equal(lateFeeByPosition('2026-03-16', '2026-03-20', 1), 200);
  // Los mismos datos, en el otro orden: ningún error, y el socio no paga.
  assert.equal(lateFeeByPosition('2026-03-20', '2026-03-16', 1), 0);
});

test('connascence de significado: un 3 que nadie definió se cobra como visitante sin avisar', () => {
  assert.equal(lateFeeByPosition('2026-03-16', '2026-03-20', 3), 600);
});
kwic/kwic.test.tsDescargar kwic/kwic.test.ts
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { fileURLToPath } from 'node:url';
import { kwic as kwicByDecisions } from './decisions/main.ts';
import { kwic as kwicBySteps } from './steps/main.ts';
import { buildVariant, modulesOf, rewrittenFor, run, typeErrors } from './variants.ts';

// Lo que el apunte afirma sobre el índice KWIC de Parnas.

const titles = join(dirname(fileURLToPath(import.meta.url)), 'titles.txt');

test('el índice KWIC lista todas las rotaciones en orden alfabético', () => {
  assert.equal(
    kwicByDecisions('Los ríos profundos\nYawar fiesta\n'),
    ['fiesta Yawar', 'Los ríos profundos', 'profundos Los ríos', 'ríos profundos Los', 'Yawar fiesta', ''].join('\n'),
  );
});

test('las dos descomposiciones producen exactamente el mismo listado', () => {
  const text = readFileSync(titles, 'utf8');
  assert.equal(kwicBySteps(text), kwicByDecisions(text));
  // 5 + 3 + 6 palabras: una rotación por palabra.
  assert.equal(kwicBySteps(text).trimEnd().split('\n').length, 14);
});

test('las líneas vacías y los espacios de más no cuentan, en ninguna de las dos', () => {
  const text = '\n  La   casa verde \n\n';
  const expected = 'casa verde La\nLa casa verde\nverde La casa\n';
  assert.equal(kwicBySteps(text), expected);
  assert.equal(kwicByDecisions(text), expected);
});

test('por pasos: cambiar cómo se guardan las líneas rompe los otros tres módulos', () => {
  const errors = typeErrors(buildVariant('steps', 'test-steps-first-step', ['formats.ts', 'input.ts']));
  assert.deepEqual([...errors.keys()].sort(), ['alphabetize.ts', 'circular-shift.ts', 'output.ts']);
});

test('por pasos: el cambio completo reescribe 5 de 6 archivos; solo se salva el control', () => {
  const rewritten = rewrittenFor('steps');
  assert.deepEqual(rewritten, ['alphabetize.ts', 'circular-shift.ts', 'formats.ts', 'input.ts', 'output.ts']);
  assert.deepEqual(modulesOf('steps').filter((file) => !rewritten.includes(file)), ['main.ts']);

  const changed = buildVariant('steps', 'test-steps-after', rewritten);
  assert.equal(typeErrors(changed).size, 0);
  assert.equal(run(changed, titles), kwicBySteps(readFileSync(titles, 'utf8')));
});

test('por decisiones: el mismo cambio reescribe un solo archivo y nadie más se entera', () => {
  const rewritten = rewrittenFor('decisions');
  assert.deepEqual(rewritten, ['line-storage.ts']);
  assert.equal(modulesOf('decisions').length, 6);

  const changed = buildVariant('decisions', 'test-decisions-after', rewritten);
  assert.equal(typeErrors(changed).size, 0);
  assert.equal(run(changed, titles), kwicByDecisions(readFileSync(titles, 'utf8')));
});
library/test/deps.test.tsDescargar library/test/deps.test.ts
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { cpSync, mkdirSync, rmSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { fileURLToPath } from 'node:url';

// Las reglas de .dependency-cruiser.cjs: el ejemplo las cumple, y cada
// variante de errors/ rompe exactamente una.

const library = join(dirname(fileURLToPath(import.meta.url)), '..');
const week = join(library, '..');

function cruise(dir: string): { status: number | null; output: string } {
  const result = spawnSync('depcruise', ['src', '--config', '.dependency-cruiser.cjs'], { cwd: dir, encoding: 'utf8' });
  return { status: result.status, output: result.stdout + result.stderr };
}

/** Copia el ejemplo a build/ y le pone encima los archivos de errors/<name>. */
function variant(name: string): string {
  const target = join(week, 'build', `test-errors-${name}`, 'library');
  rmSync(target, { recursive: true, force: true });
  mkdirSync(target, { recursive: true });
  for (const entry of ['src', '.dependency-cruiser.cjs']) cpSync(join(library, entry), join(target, entry), { recursive: true });
  cpSync(join(week, 'tsconfig.json'), join(target, '..', 'tsconfig.json'));
  cpSync(join(week, 'errors', name, 'src'), join(target, 'src'), { recursive: true });
  return target;
}

test('el ejemplo de la biblioteca cumple sus tres reglas', () => {
  const result = cruise(library);
  assert.equal(result.status, 0, result.output);
  assert.match(result.output, /no dependency violations found/);
});

for (const [name, rule] of [
  ['cycle', 'no-circular'],
  ['driver-in-core', 'core-does-not-touch-infrastructure'],
  ['deep-import', 'modules-only-through-index'],
] as const) {
  test(`errors/${name} rompe la regla ${rule}, y solo esa`, () => {
    const result = cruise(variant(name));
    assert.notEqual(result.status, 0);
    assert.match(result.output, new RegExp(`error ${rule}: `));
    assert.match(result.output, /1 dependency violations \(1 errors, 0 warnings\)/);
  });
}
library/test/loan-desk.test.tsDescargar library/test/loan-desk.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { LoanError } from '../src/loans/index.ts';
import { memoryLibrary } from '../wiring.ts';

// Pruebas del núcleo de préstamos. No usan base de datos: el núcleo recibe un
// repositorio en memoria y un reloj fijo por sus dos ports.

test('un préstamo vence 14 días después, según el reloj que recibe el núcleo', async () => {
  const { loanDesk, memberDesk } = memoryLibrary(); // el reloj marca 2026-03-02
  const rosa = await memberDesk.register('Rosa Quispe');

  const loan = await loanDesk.lend(rosa, 'YAW-001');

  assert.equal(loan.lentOn, '2026-03-02');
  assert.equal(loan.dueOn, '2026-03-16');
  assert.equal(await loanDesk.countActiveLoans(rosa.id), 1);
});

test('un ejemplar prestado no se presta otra vez', async () => {
  const { loanDesk, memberDesk } = memoryLibrary();
  const rosa = await memberDesk.register('Rosa Quispe');
  const luis = await memberDesk.register('Luis Mamani');
  await loanDesk.lend(rosa, 'YAW-001');

  await assert.rejects(
    () => loanDesk.lend(luis, 'YAW-001'),
    (error) => error instanceof LoanError && error.code === 'COPY_ON_LOAN',
  );
});

test('un socio no se lleva un cuarto libro', async () => {
  const { loanDesk, memberDesk } = memoryLibrary();
  const rosa = await memberDesk.register('Rosa Quispe');
  for (const copyCode of ['YAW-001', 'RIO-001', 'MUN-001']) await loanDesk.lend(rosa, copyCode);

  await assert.rejects(
    () => loanDesk.lend(rosa, 'CIU-001'),
    (error) => error instanceof LoanError && error.code === 'LOAN_LIMIT',
  );
  assert.equal(await loanDesk.countActiveLoans(rosa.id), 3);
});
library/test/member-desk.test.tsDescargar library/test/member-desk.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { createMemoryMemberRepository } from '../src/adapters/memory/memory-member-repository.ts';
import { createMemberDesk, MemberNotFound } from '../src/members/index.ts';

// El módulo de socios se prueba sin el de préstamos: su port ActiveLoanCounter
// se cumple con un objeto de una línea.

test('el carné muestra los préstamos que le informa quien sabe contarlos', async () => {
  const memberDesk = createMemberDesk({
    members: createMemoryMemberRepository(),
    activeLoans: { countActiveLoans: async () => 2 },
  });
  const rosa = await memberDesk.register('  Rosa Quispe ');

  assert.deepEqual(await memberDesk.card(rosa.id), {
    member: { id: rosa.id, name: 'Rosa Quispe', status: 'active' },
    activeLoans: 2,
  });
});

test('suspender un carné cambia su estado, y un socio que no existe es un error', async () => {
  const memberDesk = createMemberDesk({
    members: createMemoryMemberRepository(),
    activeLoans: { countActiveLoans: async () => 0 },
  });
  const rosa = await memberDesk.register('Rosa Quispe');

  await memberDesk.suspend(rosa.id);

  assert.equal((await memberDesk.find(rosa.id)).status, 'suspended');
  await assert.rejects(() => memberDesk.card(999), MemberNotFound);
});
library/test/memory-repository.test.tsDescargar library/test/memory-repository.test.ts
import { createMemoryLoanRepository } from '../src/adapters/memory/memory-loan-repository.ts';
import { loanRepositoryContract } from './repository-contract.ts';

loanRepositoryContract('memoria', async () => ({
  loans: createMemoryLoanRepository(),
  memberId: 1,
  otherMemberId: 2,
}));
library/test/pg-loan-desk.test.tsDescargar library/test/pg-loan-desk.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { createPool } from '../src/adapters/postgres/pool.ts';
import { LoanError } from '../src/loans/index.ts';
import { emptyTables, pgLibrary } from '../wiring.ts';

// Las mismas tres pruebas de loan-desk.test.ts, con el núcleo conectado a
// PostgreSQL. Comprueban que el sistema armado funciona; cuestan una base de
// datos con su esquema y tablas vacías antes de cada prueba.

const pool = createPool();
beforeEach(() => emptyTables(pool));
after(() => pool.end());

test('PostgreSQL: un préstamo vence 14 días después y queda en la tabla', async () => {
  const { loanDesk, memberDesk } = pgLibrary(pool);
  const rosa = await memberDesk.register('Rosa Quispe');

  const loan = await loanDesk.lend(rosa, 'YAW-001');

  assert.equal(loan.dueOn, '2026-03-16');
  const rows = await pool.query('SELECT copy_code, due_on::text, returned_on FROM loans');
  assert.deepEqual(rows.rows, [{ copy_code: 'YAW-001', due_on: '2026-03-16', returned_on: null }]);
});

test('PostgreSQL: un ejemplar prestado no se presta otra vez', async () => {
  const { loanDesk, memberDesk } = pgLibrary(pool);
  const rosa = await memberDesk.register('Rosa Quispe');
  const luis = await memberDesk.register('Luis Mamani');
  await loanDesk.lend(rosa, 'YAW-001');

  await assert.rejects(
    () => loanDesk.lend(luis, 'YAW-001'),
    (error) => error instanceof LoanError && error.code === 'COPY_ON_LOAN',
  );
});

test('PostgreSQL: un socio no se lleva un cuarto libro', async () => {
  const { loanDesk, memberDesk } = pgLibrary(pool);
  const rosa = await memberDesk.register('Rosa Quispe');
  for (const copyCode of ['YAW-001', 'RIO-001', 'MUN-001']) await loanDesk.lend(rosa, copyCode);

  await assert.rejects(
    () => loanDesk.lend(rosa, 'CIU-001'),
    (error) => error instanceof LoanError && error.code === 'LOAN_LIMIT',
  );
  assert.equal((await memberDesk.card(rosa.id)).activeLoans, 3);
});
library/test/pg-repository.test.tsDescargar library/test/pg-repository.test.ts
import { after } from 'node:test';
import { createPgLoanRepository } from '../src/adapters/postgres/pg-loan-repository.ts';
import { createPgMemberRepository } from '../src/adapters/postgres/pg-member-repository.ts';
import { createPool } from '../src/adapters/postgres/pool.ts';
import { emptyTables } from '../wiring.ts';
import { loanRepositoryContract } from './repository-contract.ts';

const pool = createPool();
after(() => pool.end());

loanRepositoryContract('PostgreSQL', async () => {
  await emptyTables(pool);
  const members = createPgMemberRepository(pool);
  const rosa = await members.add('Rosa Quispe');
  const luis = await members.add('Luis Mamani');
  return { loans: createPgLoanRepository(pool), memberId: rosa.id, otherMemberId: luis.id };
});
library/test/repository-contract.tsDescargar library/test/repository-contract.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import type { LoanRepository } from '../src/loans/index.ts';

// El contrato del port LoanRepository: lo que el núcleo supone de cualquier
// adapter. Las mismas comprobaciones se corren contra el adapter en memoria y
// contra el de PostgreSQL; si uno de los dos se comporta distinto, las pruebas
// del núcleo con el otro dejan de valer.

export type ContractSetup = () => Promise<{ loans: LoanRepository; memberId: number; otherMemberId: number }>;

export function loanRepositoryContract(adapter: string, setup: ContractSetup): void {
  test(`${adapter}: un préstamo guardado queda vigente, con id y sin fecha de devolución`, async () => {
    const { loans, memberId } = await setup();

    const saved = await loans.add({ memberId, copyCode: 'YAW-001', lentOn: '2026-03-02', dueOn: '2026-03-16' });

    assert.equal(typeof saved.id, 'number');
    assert.deepEqual(await loans.activeByCopy('YAW-001'), {
      id: saved.id,
      memberId,
      copyCode: 'YAW-001',
      lentOn: '2026-03-02',
      dueOn: '2026-03-16',
      returnedOn: null,
    });
  });

  test(`${adapter}: los préstamos vigentes de un socio salen del más antiguo al más reciente, sin los de otros`, async () => {
    const { loans, memberId, otherMemberId } = await setup();
    await loans.add({ memberId, copyCode: 'YAW-001', lentOn: '2026-03-02', dueOn: '2026-03-16' });
    await loans.add({ memberId: otherMemberId, copyCode: 'RIO-001', lentOn: '2026-03-02', dueOn: '2026-03-16' });
    await loans.add({ memberId, copyCode: 'MUN-001', lentOn: '2026-03-03', dueOn: '2026-03-17' });

    const active = await loans.activeByMember(memberId);

    assert.deepEqual(active.map((loan) => loan.copyCode), ['YAW-001', 'MUN-001']);
  });

  test(`${adapter}: un préstamo devuelto deja de estar vigente`, async () => {
    const { loans, memberId } = await setup();
    const saved = await loans.add({ memberId, copyCode: 'YAW-001', lentOn: '2026-03-02', dueOn: '2026-03-16' });

    await loans.markReturned(saved.id, '2026-03-10');

    assert.equal(await loans.activeByCopy('YAW-001'), undefined);
    assert.deepEqual(await loans.activeByMember(memberId), []);
  });

  test(`${adapter}: un ejemplar que nunca se prestó no tiene préstamo vigente`, async () => {
    const { loans } = await setup();
    assert.equal(await loans.activeByCopy('NADA-000'), undefined);
  });
}
library/test/timing.test.tsDescargar library/test/timing.test.ts
import assert from 'node:assert/strict';
import { performance } from 'node:perf_hooks';
import { after, test } from 'node:test';
import { morningAtTheDesk } from '../scenario.ts';
import { createPool } from '../src/adapters/postgres/pool.ts';
import { emptyTables, memoryLibrary, pgLibrary } from '../wiring.ts';

const pool = createPool();
after(() => pool.end());

test('el mismo escenario da el mismo resultado con los dos juegos de adapters, y en memoria tarda menos', async () => {
  await emptyTables(pool);
  await morningAtTheDesk(memoryLibrary(), 3, 'W');
  await morningAtTheDesk(pgLibrary(pool), 3, 'W');

  let start = performance.now();
  const lentInMemory = await morningAtTheDesk(memoryLibrary(), 40, 'M');
  const memoryMs = performance.now() - start;

  start = performance.now();
  const lentInPg = await morningAtTheDesk(pgLibrary(pool), 40, 'P');
  const pgMs = performance.now() - start;

  assert.equal(lentInMemory, 40);
  assert.equal(lentInPg, 40);
  // La cota es amplia a propósito: en PostgreSQL cada operación cruza un socket.
  assert.ok(memoryMs < pgMs, `memoria ${memoryMs.toFixed(1)} ms, PostgreSQL ${pgMs.toFixed(1)} ms`);
});

Laboratorio

Archivos de partida del laboratorio de la semana.

lab/loan-desk.test.tsDescargar lab/loan-desk.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { LoanError } from '../library/src/loans/index.ts';
import { memoryLibrary } from '../library/wiring.ts';

// Laboratorio, paso 5: completen las pruebas del núcleo de préstamos. Ninguna
// necesita base de datos: memoryLibrary() arma el núcleo con un repositorio en
// memoria y un reloj fijo que empieza en 2026-03-02 (clock.set('2026-03-20')
// cambia el día). Las tres primeras pruebas, ya escritas, están en
// library/test/loan-desk.test.ts.
//
//   node --test lab/loan-desk.test.ts

// Para comprobar el código de un error:
//   await assert.rejects(() => loanDesk.lend(rosa, 'YAW-001'), rejectsWith('COPY_ON_LOAN'));
function rejectsWith(code: string): (error: unknown) => boolean {
  return (error) => error instanceof LoanError && error.code === code;
}

test('un ejemplar devuelto se puede prestar a otro socio', async () => {
  const { loanDesk, memberDesk } = memoryLibrary();
  const rosa = await memberDesk.register('Rosa Quispe');
  const luis = await memberDesk.register('Luis Mamani');
  await loanDesk.lend(rosa, 'YAW-001');

  await loanDesk.giveBack('YAW-001');
  const loan = await loanDesk.lend(luis, 'YAW-001');

  assert.equal(loan.memberId, luis.id);
  assert.equal(await loanDesk.countActiveLoans(rosa.id), 0);
});

test.todo('un socio con el carné suspendido no se lleva nada (MEMBER_SUSPENDED)');

test.todo('con un préstamo vencido no se presta otro (HAS_OVERDUE): hay que mover el reloj');

test.todo('el día del vencimiento todavía no es un préstamo vencido');

test.todo('al devolver el libro vencido, el socio puede volver a llevarse uno');

test.todo('devolver un ejemplar que no está prestado es un error (NOT_ON_LOAN)');

// Para que el archivo no reclame por lo que todavía no usan.
void rejectsWith;

Compilación

Cómo se compilan y ejecutan los ejemplos.

MakefileDescargar Makefile
# Semana 3: modularidad, acoplamiento y dependencias. Se usa dentro del
# contenedor del curso.
#
#   make               crea la base de datos arq_w03 con el esquema de la
#                      biblioteca y copia Tinkuy en build/tinkuy
#   make test          revisa los tipos (tsc) y corre las pruebas (*.test.ts),
#                      que comprueban lo que dice el apunte
#   make kwic          el índice KWIC con las dos descomposiciones
#   make kwic-change   el experimento de Parnas: qué módulos toca un cambio en
#                      la forma de guardar las líneas
#   make run           el ejemplo de la biblioteca, en memoria y con PostgreSQL
#   make deps          las reglas de dependencia del ejemplo (pasan)
#   make graph         su grafo de módulos, como texto
#   make metrics       cuántos dependen de cada módulo y de cuántos depende
#   make errors        las tres variantes de errors/, cada una con su violación
#   make timing        el mismo escenario con adapters en memoria y de PostgreSQL
#   make tinkuy-deps   las violaciones de Tinkuy (sobre la copia de build/)
#   make tinkuy-graph  el grafo de módulos de Tinkuy, como texto
#   make clean         borra build/ y la base de datos
#
# Nada de esto modifica el Tinkuy del curso (../../tinkuy).

TINKUY ?= ../../tinkuy
DB = arq_w03
ROUNDS ?= 200
# psql no avisa cuando la base de datos que se va a borrar todavía no existe.
PGOPTIONS = --client-min-messages=warning
export PGOPTIONS ROUNDS

# El grafo de módulos como texto: una línea por dependencia entre carpetas de
# src/. Sirve igual para Tinkuy: es el comando del paso 2 del laboratorio.
GRAPH = depcruise src --config .dependency-cruiser.cjs --include-only '^src' --collapse '^src/[^/]+' --output-type text

TESTS = $(wildcard kwic/*.test.ts coupling/*.test.ts library/test/*.test.ts lab/*.test.ts solution/*.test.ts)

.PHONY: all db test kwic kwic-change run deps graph metrics errors timing tinkuy-deps tinkuy-graph clean

all: db build/tinkuy

db:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS $(DB) WITH (FORCE)" -c "CREATE DATABASE $(DB)"
	@psql -q -d $(DB) -v ON_ERROR_STOP=1 -f library/schema.sql

build/tinkuy:
	mkdir -p build
	cp -r $(TINKUY) $@

# Las pruebas con PostgreSQL comparten la base de datos: los archivos corren
# uno después de otro.
test: db
	tsc -p .
	node --test --test-concurrency=1 $(TESTS)

kwic:
	@echo "== kwic/steps (por pasos)"
	@node kwic/steps/main.ts kwic/titles.txt
	@echo "== kwic/decisions (por decisiones)"
	@node kwic/decisions/main.ts kwic/titles.txt

kwic-change:
	@node kwic/change.ts

run: db
	@echo "== en memoria"
	@cd library && node src/main.ts --memory
	@echo "== con PostgreSQL"
	@cd library && node src/main.ts

deps:
	cd library && depcruise src --config .dependency-cruiser.cjs

graph:
	@cd library && $(GRAPH)

metrics:
	@cd library && depcruise src --config .dependency-cruiser.cjs --include-only '^src' --output-type metrics

# Cada variante es el ejemplo con los archivos de errors/<nombre> encima.
# depcruise termina con error cuando encuentra algo: aquí eso es lo que se
# quiere ver.
errors:
	@for name in cycle driver-in-core deep-import; do \
		rm -rf build/errors/$$name; mkdir -p build/errors/$$name/library; \
		cp tsconfig.json build/errors/$$name/; \
		cp -r library/src library/.dependency-cruiser.cjs build/errors/$$name/library/; \
		cp -r errors/$$name/src build/errors/$$name/library/; \
		echo "== errors/$$name"; \
		(cd build/errors/$$name/library && depcruise src --config .dependency-cruiser.cjs); \
		echo "depcruise terminó con código $$?"; \
	done

timing: db
	@node library/timing.ts

tinkuy-deps: build/tinkuy
	-$(MAKE) --no-print-directory -C build/tinkuy deps

tinkuy-graph: build/tinkuy
	@cd build/tinkuy && $(GRAPH)

clean:
	rm -rf build
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS $(DB) WITH (FORCE)"
package.jsonDescargar package.json
{
  "private": true,
  "type": "module"
}
tsconfig.jsonDescargar tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["kwic/steps", "kwic/decisions", "kwic/*.ts", "coupling", "library", "lab", "solution"]
}