feat: executable examples of package usage

Author: jankarres

.github/workflows/ci.yml

@@ -43,6 +43,12 @@ jobs:
             - name: Build package
               run: pnpm run build
 
+            - name: Run examples
+              run: |
+                  pnpm run example:wav-to-mp3
+                  pnpm run example:mp3-to-wav
+                  pnpm run example:stream
+
     postinstall:
         name: LAME install on ${{ matrix.os }}
         runs-on: ${{ matrix.os }}

.gitignore

@@ -39,4 +39,6 @@ dist/
 # Test
 coverage/
 coverage-unit.json
-test/encoded.mp3
+
+# Examples
+examples/audios/example.*.*

AI_AGENT_INSTRUCTION.md AI_AGENT_INSTRUCTIONS.mdAI_AGENT_INSTRUCTION.md renamed to AI_AGENT_INSTRUCTIONS.md

@@ -63,6 +63,13 @@ You operate as a senior Node.js and TypeScript backend engineer focused on maint
 - Keep `normalizeCliMessage` translating warnings and errors into `lame:` prefixed messages to signal user-visible issues consistently.
 - When adding new parsing rules, guard them with unit tests to prevent regressions on partial output lines or malformed data.
 
+## Examples
+- Place runnable demos under `examples/` as TypeScript ESM files and invoke them through `pnpm example:*` scripts that rely on `tsx`; update `package.json` scripts whenever a new example is added.
+- Keep shared logic (dynamic `node-lame` resolution, temp-file cleanup, etc.) inside `examples/helpers/` and reuse those utilities to avoid duplicating `ENOENT` guards or import fallbacks.
+- Build all paths via `new URL("./audios/<file>", import.meta.url)` (wrapped with `fileURLToPath`/`resolve`) instead of `__dirname` so the code mirrors production ESM usage.
+- Examples must log encoder/decoder progress through the emitter APIs and ensure they clean up/overwrite destination files before running to keep reruns deterministic.
+- Whenever a new recipe is added, update `package.json` and `.github/workflows/ci.yml` so the corresponding `pnpm example:*` script runs during CI; the pipeline is the canonical source of truth for example coverage.
+
 ## Error Handling
 - Throw descriptive `Error` instances; avoid silent failures or rejected promises without context.
 - Exit code `255` triggers a tailored error message about unexpected termination—preserve this behaviour for backwards compatibility.

examples/audios/example.mp3

@@ -0,0 +1,35 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Lame } from "./helpers/load-node-lame.js";
+import { removeIfExists } from "./helpers/remove-if-exists.js";
+
+const inputPath = resolve(
+    fileURLToPath(new URL("./audios/example.mp3", import.meta.url)),
+);
+const outputPath = resolve(
+    fileURLToPath(new URL("./audios/example.from-mp3.wav", import.meta.url)),
+);
+
+async function main(): Promise<void> {
+    await removeIfExists(outputPath);
+
+    const decoder = new Lame({
+        output: outputPath,
+    }).setFile(inputPath);
+
+    decoder.getEmitter().on("progress", ([progress, eta]) => {
+        process.stdout.write(
+            `Decoding progress: ${progress}%${eta ? ` – ETA ${eta}` : ""}\r`,
+        );
+    });
+
+    await decoder.decode();
+
+    console.log(`Created WAV at ${outputPath}`);
+}
+
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

examples/audios/example.wav

@@ -0,0 +1,41 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+
+import { createLameEncoderStream } from "./helpers/load-node-lame.js";
+import { removeIfExists } from "./helpers/remove-if-exists.js";
+
+const inputPath = resolve(
+    fileURLToPath(new URL("./audios/example.wav", import.meta.url)),
+);
+const outputPath = resolve(
+    fileURLToPath(new URL("./audios/example.stream.mp3", import.meta.url)),
+);
+
+async function main(): Promise<void> {
+    await removeIfExists(outputPath);
+
+    const encoderStream = createLameEncoderStream({
+        bitrate: 192,
+    });
+
+    encoderStream.getEmitter().on("progress", ([progress, eta]) => {
+        process.stdout.write(
+            `Streaming progress: ${progress}%${eta ? ` – ETA ${eta}` : ""}\r`,
+        );
+    });
+
+    await pipeline(
+        createReadStream(inputPath),
+        encoderStream,
+        createWriteStream(outputPath),
+    );
+
+    console.log(`Streamed MP3 written to ${outputPath}`);
+}
+
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

examples/convert-mp3-to-wav.ts

@@ -0,0 +1,38 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Lame } from "./helpers/load-node-lame.js";
+import { removeIfExists } from "./helpers/remove-if-exists.js";
+
+const inputPath = resolve(
+    fileURLToPath(new URL("./audios/example.wav", import.meta.url)),
+);
+const outputPath = resolve(
+    fileURLToPath(new URL("./audios/example.from-wav.mp3", import.meta.url)),
+);
+
+async function main(): Promise<void> {
+    await removeIfExists(outputPath);
+
+    const encoder = new Lame({
+        output: outputPath,
+        bitrate: 192,
+    });
+
+    encoder.setFile(inputPath);
+
+    encoder.getEmitter().on("progress", ([progress, eta]) => {
+        process.stdout.write(
+            `Encoding progress: ${progress}%${eta ? ` – ETA ${eta}` : ""}\r`,
+        );
+    });
+
+    await encoder.encode();
+
+    console.log(`Created MP3 at ${outputPath}`);
+}
+
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

examples/convert-stream-to-mp3.ts

@@ -0,0 +1,58 @@
+type NodeLameModule = typeof import("../../src/index");
+
+const MODULE_NOT_FOUND_CODE = "ERR_MODULE_NOT_FOUND";
+const LOCAL_FALLBACKS = ["../../dist/index.cjs", "../../src/index.ts"] as const;
+
+type ErrorWithCode = {
+    code?: string;
+};
+
+const isModuleNotFoundError = (
+    error: unknown,
+): error is ErrorWithCode => {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+
+    return (
+        "code" in error &&
+        (error as ErrorWithCode).code === MODULE_NOT_FOUND_CODE
+    );
+};
+
+const resolveLocalModule = async (): Promise<NodeLameModule> => {
+    for (const relativePath of LOCAL_FALLBACKS) {
+        try {
+            const moduleUrl = new URL(relativePath, import.meta.url);
+            return (await import(moduleUrl.href)) as unknown as NodeLameModule;
+        } catch (error) {
+            if (isModuleNotFoundError(error)) {
+                continue;
+            }
+
+            throw error;
+        }
+    }
+
+    throw new Error(
+        'node-lame: Unable to locate local sources. Run "pnpm build" or ensure src/ is available.',
+    );
+};
+
+const loadNodeLame = async (): Promise<NodeLameModule> => {
+    try {
+        return (await import("node-lame")) as unknown as NodeLameModule;
+    } catch (error) {
+        if (isModuleNotFoundError(error)) {
+            return resolveLocalModule();
+        }
+
+        throw error;
+    }
+};
+
+const nodeLame = await loadNodeLame();
+
+export const { Lame, createLameDecoderStream, createLameEncoderStream } =
+    nodeLame;
+export default nodeLame;

examples/convert-wav-to-mp3.ts

@@ -0,0 +1,27 @@
+import { unlink } from "node:fs/promises";
+
+type ErrorWithCode = {
+    code?: string;
+};
+
+const isEnoentError = (error: unknown): error is ErrorWithCode => {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+
+    return "code" in error && (error as ErrorWithCode).code === "ENOENT";
+};
+
+const removeIfExists = async (filePath: string): Promise<void> => {
+    try {
+        await unlink(filePath);
+    } catch (error) {
+        if (isEnoentError(error)) {
+            return;
+        }
+
+        throw error;
+    }
+};
+
+export { removeIfExists };