Remeda Utility

A new or modified Remeda function ships across five surfaces: implementation, tests, JSDoc, the public export, and — when there's a Lodash/Ramda equivalent — migration mappings on the docs site. Skipping any one of them leaves the function half-shipped (e.g., a working implementation that isn't re-exported, or a behavior change with no test covering it). Work through the sections in order — later sections assume the earlier ones are in place.

1. Implementation (src/functionName.ts)

When any of the edits involves the runtime implementation of a function, one of its overloading function signatures, or any of the type definitions that it uses (either directly on the same file, or indirectly via imports) read reference/implementation.md.

2. Tests

Each function has up to three test files, one per kind:

• Runtime tests (functionName.test.ts) — Vitest. Cover happy path, edge cases, empty inputs, and both calling styles (data-first and data-last inside pipe, map or filter). When editing, read reference/testing-runtime.md.
• Type tests (functionName.test-d.ts) — expectTypeOf from Vitest. Verify inferred return types, narrowing, and that invalid inputs are compile errors. When editing, read reference/testing-types.md.
• Property-based tests (functionName.test-prop.ts) — @fast-check/vitest. Optional but encouraged for functions with well-defined algebraic properties (idempotence, involutions, round-trips). When adding, read reference/testing-properties.md.

Conventions that apply across all three kinds:

• Runtime and type assertions are strictly separated — expect() lives in .test.ts, expectTypeOf() lives in .test-d.ts. Never mix them in the same test block, and never put one kind in the other file.
• Test names describe what is being tested in the function's own vocabulary — "lazy early exit with hasMany", not "take and flat".
• Test names should be terse and concise, and should rely on context from parent describe() blocks and not repeat them.
• Test names do not need to read as prose!
• Tests for a specific bug must reference the issue number, either in the test name or a comment so that the reporting issue can always be traced back.
• Input data needs enough variation to produce distinct outputs — [1, 1, 1] hides bugs that [1, 2, 3] catches.

3. JSDoc

Each overload needs its own JSDoc block. Required tags:

If the new function is closely related to others where a user might pick the wrong one (e.g., indexBy vs. fromKeys vs. pullObject vs. fromEntries), list those alternatives with a one-line "use this when…" gloss in the description body of every overload. Update the related functions' JSDoc to cross-reference back, so the disambiguation is symmetric — a user who lands on either function discovers the others.

The function description, @params, @returns, and @deprecated should be copied verbatim between the overloads, unless there is a strong reason not to, and then that reason should be made extremely clear in both blocks.

4. Export

Add export * from "./functionName"; to src/index.ts (alphabetical order).

5. Migration Mappings

Many Remeda functions are genuinely novel and have no Lodash, Ramda, or Just counterpart — those skip this section entirely. But if the function has a matching upstream function (or replaces one), it needs a per-library mapping page on the docs site so migrators landing from a search for the upstream name find a clean answer for their call site.

Read reference/migration.md when:

• Authoring a new Remeda function that has a Lodash, Ramda, or Just equivalent.
• Editing any existing file under packages/docs/src/content/mapping/{lodash,ramda,just}/.
• Reviewing changes that add or modify a mapping page.

reference/migration.md covers the file location and frontmatter, the bullets-then-examples body structure, the comment-header convention inside code blocks (// Lodash / // Remeda / // Native), the linking rules, and the __MISSING.md cleanup. This is interim guidance — eventually migration work will live behind its own skill, but until then this reference is the source of truth.

Source: remeda/remeda — distributed by TomeVault.