lodash/lodash
github.com/lodash/lodash ↗ · 64 files · 1.8 MB
lodash v4.18.1 Site | Docs | FP Guide | Contributing | Wiki | Code of Conduct | Governance | Twitter | Chat [!IMPORTANT] As announced on the OpenJS Foundation blog, Lodash has received support from the Sovereign Tech Agency and will transition to the Feature-C
Overview
This is the lodash monorepo root: the hand-maintained single-file UMD source `lodash.js` (v4.18.1, ~546 KB, one IIFE wrapping a `runInContext` factory), the `fp/` converter that re-wraps every method into immutable auto-curried iteratee-first data-last form, and a small Node build/doc toolchain under `lib/` that copies, minifies, webpacks, and doc-generates artifacts into `dist/` and `doc/`. It is not an application — it is a library plus its release machinery, consumed by downstream repos (`lodash-cli`, the `npm` branch) that call `build:main-modules`/`build:fp-modules` with a target directory. What's distinctive is the test posture: ~1750 QUnit assertions in a single 814 KB `test/test.js` that deliberately sabotages host globals ("bizarro" shims), plus vendored Backbone and Underscore suites run against lodash, driven in Node and across six Playwright browser projects. The repo is now under OpenJS Foundation governance with a published threat model that explicitly scopes prototype pollution and `_.template` code injection as in-scope vulnerability classes.
System map
There is no server or CLI entrypoint; the shipped artifact is `lodash.js`, declared as `main` in a `private: true` package.json, exported via a three-way UMD tail (AMD `define`, CommonJS `freeModule.exports`, global `root._`). All build logic lives in `lib/`, split into `lib/common/` (file copy, uglify wrapper, error-throwing callback, Hash), `lib/main/` (dist, modules, docdown, site HTML) and `lib/fp/` (webpack dist, `.jst`-templated module emission, FP wiki). The only persistent storage is the filesystem: `dist/` for builds and `doc/README.md` for generated API docs. Eight GitHub Actions workflows cover Node 4–25, four Bun versions, browser matrix, docs generation, dist-sync verification, CodeQL, OSSF Scorecard and Renovate. Deployment is out-of-repo — the Release Team publishes to npm, and `dist/lodash.core.js` is produced by the external `lodash-cli`, not by `npm run build`.
- The package is `private: true` with `main: "lodash.js"` and `engines.node >= 4.0.0`, so the repo itself is never published; it is the source-of-truth checkout that other release tooling consumes.
- `lodash.js` is a single `;(function() { ... }.call(this))` IIFE whose entire API is built inside a `runInContext(context)` factory at line 1449; the module-level `var _ = runInContext()` at line 17232 creates the default instance.
- The export tail branches three ways in strict order — AMD `define.amd` (also assigning `root._` to survive script-tag loading), then `freeModule.exports` for Node/CommonJS, then a bare global assignment — which is why the file works unchanged in every listed CI runtime.
- Runtime-boundary detection is done once at the top level via `freeGlobal`/`freeSelf`/`Function('return this')()` for `root`, plus `freeExports`, `freeModule`, `moduleExports` and `freeProcess` for Node-only features like `Buffer` and `util.types`.
- `npm run build` is only `build:main && build:fp`: `lib/main/build-dist.js` copies `lodash.js` → `dist/lodash.js` and minifies it, while `lib/fp/build-dist.js` runs two webpack passes (`fp/_mapping.js` → `dist/mapping.fp.js`, `fp/_convertBrowser.js` → `dist/lodash.fp.js`, both UMD) then minifies.
- Minification is centralized in `lib/common/minify.js`, which shells into `uglify-js@2.7.5` with `unsafe: true`, `pure_getters: true`, `ascii_only: true` and a `/@license/` comment filter from `lib/common/uglify.options.js`.
- All build scripts share the same async shape: `lib/common/file.js` returns `_.partial`-applied `fs.copy`/`minify`/`fs.writeFile` thunks that are handed to `async.series` with `util.pitch` as the terminal callback, and `pitch` simply rethrows any error.
- `lib/common/mapping.js` wraps `fp/_mapping.js` in a null-prototype `Hash` (recursively, via `_.transform` with `Hash.prototype = Object.create(null)`), so build-time lookups like `mapping.skipFixed[name]` can't collide with inherited `Object.prototype` keys.
- Documentation is a two-stage pipeline: `lib/main/build-doc.js` runs `docdown` over `lodash.js` in either `github` or `site` style and writes `doc/README.md`; `lib/main/build-site.js` then feeds that markdown through `marky-markdown` + `cheerio` and emits `doc/<version>.html` with Jekyll front matter.
- `doc/README.md` is a checked-in 295 KB generated artifact (its first line carries the `v4.18.1` docdown title), and `doc/*.html` is gitignored — so the markdown is versioned but the site HTML is not.
- Eight workflows exist: `ci-node.yml` (Node 4 through 25 on ubuntu, `npm run validate`), `ci-bun.yml` (Bun 1.0–1.3), `browser-testing.yml` (Playwright), `ci-docs.yml`, `ci-dist-sync.yml`, `codeql.yml`, `scorecards.yml`, `renovate.yml`.
- Every third-party action is SHA-pinned (e.g. `actions/checkout@3d3c42e5...` v7.0.1, `github/codeql-action/init@b96794f0...` v4.38.0), and Renovate is self-hosted monthly with `minimumReleaseAge: 14d` and npm major updates disabled.
Feature catalog
User-facing surface is the lodash API itself (~300 methods attached to the `lodash` function plus a lazy-evaluating chain wrapper), the `fp` variant, and the four per-method build/doc npm scripts. `fp/_mapping.js` is the declarative feature table that defines the entire FP surface: aliases, arity buckets, rearg orders, spread configs, mutation classes and skip lists. The repo also ships two interactive HTML surfaces — a QUnit test runner with build/loader dropdowns, and a Benchmark.js perf page comparing lodash against Underscore. There is no HTTP API, no routes, and no CLI subcommands; the `lib/*/build-*.js` scripts are the closest thing to commands and take their target directory from the last `process.argv` element.
- The full lodash API is assembled by explicit `lodash.<name> = <fn>` assignment inside `runInContext`, including `lodash.runInContext`, `lodash.VERSION` and the chainable `lodash.prototype.*` sequence methods (`at`, `chain`, `commit`, `next`, `plant`, `reverse`, `toJSON`/`valueOf`/`value`).
- Lazy evaluation is a first-class feature: `LazyWrapper.prototype.clone/reverse/value` are installed and a `realNames` registry maps minified function names back to method names so shortcut fusion survives minification.
- `fp/_mapping.js` declares the FP surface across 12 exported tables — `aliasToReal`, `aryMethod`, `aryRearg`, `iterateeAry`, `iterateeRearg`, `methodRearg`, `methodSpread`, `mutate`, `realToAlias`, `remap`, `skipFixed`, `skipRearg`.
- The FP immutability guarantee is table-driven: `mapping.mutate` classifies mutating methods into `array` (fill, pull*, remove, reverse), `object` (assign*, defaults*, merge*) and `set` (set, setWith, unset, update, updateWith), each wrapped with a different cloner.
- `fp/_convertBrowser.js` self-installs when loaded after lodash in a browser: if a global `_` with `runInContext` exists, it reassigns `_ = browserConvert(_.runInContext())`, converting the page's lodash in place.
- FP conversion is configurable per-call and per-method through five boolean options — `cap`, `curry`, `fixed`, `immutable`, `rearg` — each defaulting to `true`, exposed as `fp.convert({...})` and `fp.someMethod.convert({...})`.
- `npm run build:main-modules <target>` copies `dist/lodash.core.js`, `dist/lodash.core.min.js` and `dist/lodash.min.js` into a target directory as `core.js`, `core.min.js` and `lodash.min.js` — the per-method npm package layout.
- `npm run build:fp-modules <target>` globs the target's existing `*.js` modules (ignoring `_*.js`, `core.js`, `fp.js`, `index.js`, `lodash.js`), adds alias and remap paths, and emits one `fp/<name>.js` per method chosen from four `.jst` templates (`alias`, `category`, `thru`, `module`).
- `npm run doc:fp` renders the public FP-Guide wiki page from `lib/fp/template/doc/wiki.jst`, computing the method lists at build time with helpers `toFuncList` (sorted, chunked by 5) and `toArgOrder` (index permutation → `(a, b, c)` string).
- The QUnit runner page exposes a build selector (lodash dev/prod, lodash-core dev/prod) and a loader selector (none, Curl, Dojo, RequireJS) that rewrite `location.href` query params, letting a human test any build/loader combination in-browser.
- `perf/index.html` plus `perf/perf.js` is a Benchmark.js A/B suite that loads lodash and a comparison library (default Underscore), scores each into `score.a`/`score.b`, and renders output through an embedded Firebug Lite console.
- `test/remove.js` is a small standalone Node utility that takes a `/pattern/flags` string plus a file path and strips matched line groups in place — used to prune generated sources.
Data flow
Two distinct flows exist. At library runtime, data enters as plain JS values through method arguments, is normalized by `castPath`/`toKey`/`baseIteratee`, mutated or cloned by `base*` internals, and exits either as a new value or — in chain mode — as a `LazyWrapper`/`lodash` wrapper holding `__wrapped__` and an `__actions__` queue that is only drained on `.value()`. At build time, the input boundary is `lodash.js` plus `fp/_mapping.js`; transforms are `fs.copy`, `uglify.minify`, `webpack`, `docdown` and `_.template`-compiled `.jst` files; the output boundary is the filesystem (`dist/`, `doc/`, or an arbitrary `target` from `process.argv`). The FP path is unusual: `_mapping.js` is pure data that is read three times — by `_baseConvert` at runtime, by `build-modules.js` to decide which template to emit, and by `build-doc.js` to render the wiki.
- Property paths are the main untrusted input boundary: `castPath` converts strings/arrays to key arrays and `toKey` normalizes each segment before any read or write in `baseGet`/`baseSet`/`baseUnset`.
- Writes funnel through `assignValue` → `baseAssignValue`, which special-cases the key `__proto__` by using `Object.defineProperty` with an own data descriptor rather than plain assignment, so it lands on the object instead of the prototype.
- Deep merge reads go through `safeGet`, which returns `undefined` for `__proto__` and for `constructor` when it resolves to a function — cutting the read side of the pollution chain.
- Chain state lives on the wrapper instance: `mixin` installs prototype methods that clone `__actions__` via `copyArray`, push `{func, args, thisArg}`, carry `__chain__` forward, and defer execution until `.value()`.
- In `_baseConvert`, each method flows through a fixed transform pipeline — immutability wrapper → `castFixed` (arity cap or `flatSpread`) → `castRearg` (argument permutation) → `castCap` (iteratee arity cap) → `castCurry` — with `methodSpread[name].afterRearg` deciding whether fixed or rearg runs first.
- The FP converter owns two state sources: a `pristine = func.runInContext()` snapshot used so `.convert()` re-derives from unconverted methods, and a `defaultHolder` placeholder that is stamped onto both the wrapped and original function as `.placeholder`.
- Conversion output is assembled as `pairs` of `[name, wrappedFn]` — first for every name in `mapping.aryMethod[1..4]`, then for remaining own function keys — and only then assigned back onto `_`, deliberately leaving `_.prototype` untouched so chaining still works.
- `_.set`-family immutability in FP is achieved by `cloneByPath`, which walks the resolved path cloning each level but skipping values that are functions, errors or WeakMaps.
- Build data flows from `fp/_mapping.js` → `lib/common/mapping.js` (null-prototype Hash) → `lib/fp/build-modules.js`, where `_.union(mapping.aryMethod[1..4])` forms `aryMethods` and drives the `isThru` decision for every emitted module.
- `.jst` templates are compiled to functions at require time by `file.globTemplate`, which globs `*.jst`, keys them by basename, and runs each through `_.template` — so `template.module`, `template.alias`, `template.wiki` are lodash templates executed with `{name, mapping}` data.
- The doc HTML flow mutates markdown through five ordered regex rewrites (uncommenting docdown HTML hints, converting `[source]`/`[npm package]` links after `<h3>`) before Cheerio DOM passes `autoLink`, `renameLodashId`, `removeHorizontalRules`, `removeMarkyAttributes`, `repairMarkyHeaders`, `tidyHighlights`.
- The site build derives its output filename from the document itself — it removes the first `<h1>`, reads the version out of its `<span>`, and writes `doc/<version>.html`; if that span is missing the front matter records `version: null`.
Behavior traces
Four flows matter here: library initialization, an FP conversion, the `npm test` path, and the browser-test path. Library init is entirely synchronous at require time. The Node test path is unusual because `pretest` forces a full build first, meaning `npm test` cannot run without webpack and uglify succeeding. The browser path is a three-stage `document.write` cascade that deliberately corrupts globals before loading lodash, snapshots the result as `lodashBizarro`, restores the globals, then loads the real build and the suite.
- Library startup: the outer IIFE defines constants and regexes → detects `freeGlobal`/`root`/`freeModule` → defines `runInContext` → calls `var _ = runInContext()` at line 17232 → picks one of three export branches. No async work and no I/O occurs.
- Inside `runInContext`, the sequence is: default the context from `contextProps` → alias built-ins (`Array`, `Object`, `Function`, …) → derive `maskSrcKey` from `context['__core-js_shared__']` → build `reIsNative` from `funcToString.call(hasOwnProperty)` → define all internals → attach them to `lodash` → return `lodash`.
- FP conversion of the whole library: `baseConvert(util, name, func, options)` detects `isObj`/`isLib` → builds `config` from the five option flags → snapshots `pristine` → iterates `mapping.aryMethod[1..4]` calling `wrap(key, func, _)` for each → sweeps remaining own function keys attaching only `.convert` → assigns all pairs onto `_` → sets `_.convert` and `_.placeholder` → finally assigns aliases.
- A single method's wrap: `wrap()` resolves `realName` via `aliasToReal` → applies a named special-case wrapper if one exists in `wrappers` (castArray, iteratee, mixin, nthArg, rearg, runInContext) → else applies `wrapImmutable` with the cloner chosen from `mapping.mutate` → then runs the castFixed/castRearg/castCap/castCurry chain → attaches `.convert` and `.placeholder`.
- `npm test` fires `pretest` → `npm run build` → `build:main` (copy + minify) → `build:fp` (webpack mapping, webpack fp, minify) → then `test:main` = `node test/test` and `test:fp` = `node test/test-fp`.
- `node test/test` bootstrap: resolve `filePath` from argv (defaulting to `../lodash.js`, then `fs.realpathSync` + `require.resolve`) → build the `ui` object with `isModularize`/`isStrict` flags → poison `global.root` with a throwing getter → require `qunit-extras` → load the previous stable lodash from `node_modules/lodash/lodash.js` as `lodashStable` → `interopRequire(filePath)` as `_`.
- `test.js` then reaches into internals for coverage: it derives `Hash`, `MapCache`, `ListCache` and `Stack` constructors by inspecting `_.memoize.Cache.__data__.hash.constructor` and by capturing the stack argument passed to an `_.isMatchWith` customizer.
- At the end of both Node suites the same tail runs: set `QUnit.config.asyncRetries = 10` and `hidepassed = true`, and when `document` is absent set `noglobals = true` then `QUnit.load(); QUnit.start();`.
- `test-fp.js` startup differs: it builds a `convert` shim that dispatches to either `root.fp` (browser, pre-built `dist/lodash.fp.js`) or `require('../fp/_baseConvert.js')` (Node), then produces `fp` either by `_.noConflict()` juggling or by `convert(_.runInContext())`.
- Browser test startup, stage 1: `test/index.html` loads stable lodash + QUnit + qunit-extras + platform + `test-ui.js`, calls `addBizarroMethods()` to null out `Object.create`, `Object.getOwnPropertySymbols`, `Symbol`, `Promise`, `Set`, `WeakMap` and patch `Function.prototype.toString`, then `document.write`s `ui.buildPath`.
- Stage 2 captures the sabotaged instance as `lodashBizarro`, clears `window._`, calls `removeBizarroMethods()` to restore every global, then `document.write`s either the build + `test.js` directly or the selected AMD loader.
- Stage 3 (AMD path) configures the loader with three package aliases pointing at the same files through different paths — `lodash`, `shimmed` (`./abc/../`) and `underscore` (`./xyz/../`) — loads all three, tags each with `moduleName`, optionally pulls `_baseEach`/`_isIndex`/`_isIterateeCall`, then `require(['test'])` and `QUnit.start()`.
Testing signals
Testing is QUnit 2 (`qunitjs` + `qunit-extras`) driven two ways: directly under Node via `node test/test` and `node test/test-fp`, and in browsers via Playwright asserting `0 failed` on four static pages. Coverage of the main library is very broad — 307 QUnit modules and ~1754 assertions in `test/test.js` alone, plus 85/134 for FP — and is supplemented by running the vendored Backbone and Underscore suites against lodash. Style is enforced by JSCS across `lodash.js`, `fp/`, `lib/`, `perf/` and `test/`, and docs are tested by executing every README code fence via `markdown-doctest`. The notable gaps are the `lib/` build scripts themselves and the Playwright runner's coarse assertion.
- `test/test.js` contains 307 `QUnit.module(` and 1754 `QUnit.test(` calls in a single 814 KB file; `test/test-fp.js` adds 85 modules and 134 tests.
- `npm run validate` is the CI gate everywhere — it chains `npm run style` (four JSCS invocations) and `npm test` — and is what both `ci-node.yml` and `ci-bun.yml` run.
- The Node matrix is exhaustive and non-fail-fast: Node 4 through 25 on ubuntu-latest, with a special step installing `npm@3.10.10` for Node 5 because of npm 3 package-format bugs.
- Bun CI needs a workaround before it can install: it runs `npm i --lockfile-version 3 --package-lock-only` first because the committed `package-lock.json` is an older lockfile version, flagged with a TODO.
- Browser coverage runs six Playwright projects (Chromium, Firefox, WebKit, Microsoft Edge via msedge channel, Mobile Safari/iPhone 12, Mobile Chrome/Pixel 5) with `retries: 2` under CI and a 120s per-test timeout chosen to exceed the 60s in-page wait.
- Each Playwright spec asserts only that the literal text `0 failed` becomes visible — it does not read which tests ran, so a page that silently fails to load its suite and renders nothing will time out rather than report a specific failure.
- Cross-library regression coverage: `test/backbone.html` runs Backbone's own 7 test files against lodash after `mixin`-ing 17 lodash methods and aliasing `indexBy`→`keyBy`, `invoke`→`invokeMap`, `rest`→`tail`.
- `test/underscore.html` runs Underscore's 7 suites against lodash and carries a large `QUnit.config.excused` map enumerating known, accepted behavioral divergences (e.g. `chunk` size 0, `difference` OO-style, `drop` alias).
- The suite tests lodash against a deliberately hostile environment: `addBizarroMethods` removes `Object.create`/`Symbol`/`getOwnPropertySymbols`, stubs `Promise`/`Set`/`WeakMap` with `noop`, makes `Map` return a plain object on first construction, and fakes `WinRTError` plus `global`/`exports`/`module`.
- There is an explicit minification guard test asserting no exported method name is ≤2 characters except `_`, `at`, `eq`, `gt`, `lt` — catching accidentally shipped minified production builds.
- Documentation is executable: `npm run test:doc` runs `markdown-doctest doc/*.md` with a setup file that deletes `global['__core-js_shared__']` and injects the real `_` plus `lodash-doc-globals` into every example's scope.
- JSCS enforces ~40 rules including `requireEarlyReturn`, `disallowKeywords: ["with"]`, `validateQuoteMarks: '`, 2-space indentation and JSDoc type/param/return checks, but with `maxErrors: 2000` so a large backlog can exist without failing.
Risk map
The security-sensitive surface is narrow but sharp: `_.template` compiles to a real `Function`, and the path-write family (`_.set`, `_.unset`, `_.merge`, `_.defaultsDeep`) has layered prototype-pollution guards that are the subject of prior CVEs. The repo's own `threat-model.md` scopes these precisely. Structurally, the largest risk is coupling: `lodash.js` is 546 KB in one file that every contributor edits, `test/test.js` is 814 KB, and `fp/_mapping.js` is a hand-maintained table that must stay in lockstep with the method list or the FP build silently drifts. `dist/lodash.core.js` is not produced by `npm run build`, so the dist-sync workflow cannot detect a stale core build. CI also pulls two unpinned packages from the network at test time.
- `_.template` builds a source string and evaluates it with `Function(importsKeys, sourceURL + 'return ' + source)`; the project's own threat model calls it insecure, cites CVE-2021-23337, and states it will be removed in v5.
- `_.template`'s hardening is two regex checks: `sourceURL` has all whitespace collapsed to spaces so a newline can't escape the `//#` comment, and `variable` is rejected if it matches `/[()=,{}\[\]\/\s]/`.
- `baseSet` returns the object untouched if any path segment is `__proto__`, `constructor` or `prototype` — a blanket block that also silently no-ops legitimate writes to a literal `constructor` key.
- `baseUnset` uses a different, narrower rule than `baseSet`: it blocks `__proto__` only when the object lacks an own `__proto__`, and blocks `constructor`/`prototype` only in non-terminal positions — the asymmetry is deliberate but easy to break when editing one and not the other.
- Prototype-pollution defense is spread across four unrelated call sites — `baseAssignValue`, `baseSet`, `baseUnset`, `safeGet` — plus `isKey`'s `value !== '__proto__'` check, so a new path-writing method added without touching all of them would be unprotected. (inferred)
- `dist/lodash.core.js` carries the header `Build: lodash --source ./lodash.js core -o ./dist/lodash.core.js` and is produced by the external `lodash-cli`; `npm run build` only regenerates `lodash.js`, `lodash.min.js`, `lodash.fp.js` and `mapping.fp.js`.
- Because `npm run build` never writes `dist/lodash.core*.js`, `ci-dist-sync.yml`'s `git diff --exit-code dist/` will pass even when the core build is stale relative to an edited `lodash.js` — a silent staleness hole in the sync gate. (inferred)
- `browser-testing.yml` installs two packages that are not in `package.json` and are unpinned: `npm install -D @playwright/test@latest` and `npx http-server`, both fetched from the registry on every CI run despite every GitHub Action being SHA-pinned.
- `npm run doc:fp` invokes `node lib/fp/build-doc` with no target argument, so `_.last(process.argv)` resolves to the script's own path and `fs.writeFile(target, ...)` writes the wiki output next to the build script rather than to an intended doc location.
- The build toolchain is pinned to end-of-life tooling: `uglify-js` exactly `2.7.5`, `webpack ^1.14.0` (using the webpack-1-only `OccurenceOrderPlugin` and `DedupePlugin`), `jscs ^3.0.7` and `istanbul 0.4.5`, while Renovate is configured to never propose major npm updates.
- The test suite deletes and replaces host globals (`Object.create`, `Symbol`, `Map`, `Promise`, `Set`, `WeakMap`, `Function.prototype.toString`) and restores them by hand in a separate function — an asymmetry that leaks global state into all subsequent tests if `removeBizarroMethods` drifts from `addBizarroMethods`.
- `test/test.js` intentionally defines a non-configurable throwing getter on `global.root` and calls `require('vm').runInNewContext` to build a cross-realm fixture — both are process-level side effects that make the suite hostile to running inside other harnesses.
Extension points
The intended way to add a method is: implement it in `lodash.js`, attach it with `lodash.<name> = <name>` in the assignment block, add tests in `test/test.js`, and — if it should exist in FP form — register it in the right `fp/_mapping.js` tables. `fp/_mapping.js` is the real registry: arity bucket, rearg order, iteratee cap, spread config, mutation class, alias and remap are all declarative. `_baseConvert`'s `wrappers` object is the escape hatch for methods whose conversion can't be expressed in tables. At runtime, `_.mixin` and `_.runInContext` are the library's public extension APIs, and `templateSettings` is the configuration hook for `_.template`.
- The method registry is the literal assignment block near the end of `runInContext` — every public method appears as `lodash.<name> = <name>`, and omitting a line there makes an implemented function unreachable.
- `mapping.aryMethod[1|2|3|4]` is the primary FP registration point: `_baseConvert` iterates exactly these buckets to decide which methods get wrapped, and `lib/fp/build-modules.js` unions them into `aryMethods` to decide `module.jst` vs `thru.jst`.
- `_baseConvert`'s `wrappers` object is a named override table — `castArray`, `iteratee`, `mixin`, `nthArg`, `rearg`, `runInContext` each get bespoke conversion logic that bypasses the table-driven pipeline.
- `mapping.remap` lets an FP-only method name map onto a different real lodash method, and `build-modules.js` reads it both to emit extra module paths and, via `_.get(mapping.remap, name, name)`, to write the correct `require` inside the generated module.
- `mapping.aliasToReal` drives three things at once: alias resolution inside `wrap()`, the `alias.jst` re-export module, and the generated FP-Guide's alias listing.
- Opting a method out of FP transforms is declarative: add its name to `mapping.skipFixed` (no arity cap) or `mapping.skipRearg` (no argument reordering), both read inside `castFixed`/`castRearg`.
- The `lib/fp/template/modules/*.jst` set is the emission plugin surface — `getTemplate()` dispatches to `alias`, `category`, `thru` or `module` based on `isAlias`/`isCategory`/`isThru`, so a new module shape means a new `.jst` plus a branch there.
- `file.globTemplate` auto-discovers templates by glob and keys them by basename, so dropping a new `.jst` into `lib/fp/template/modules/` makes it available as `template.<basename>` without registering it anywhere.
- `_.mixin(object, source, options)` is the public plugin API: it walks `baseFunctions(source)`, assigns each onto the target, and when the target is a function also installs a chain-aware prototype method honoring `options.chain`.
- `_.runInContext(context)` is the sandboxing extension point — the `contextProps` array enumerates the 30 substitutable globals, documented with the example of swapping `setTimeout` for `setImmediate`.
- `lodash.templateSettings` is the documented configuration object for `_.template`'s `escape`/`evaluate`/`interpolate` delimiters, `imports` and `variable`, read at the top of `template()`.
- The doc pipeline is configured by the `config` object in `lib/main/build-doc.js`, keyed `base`/`github`/`site` and merged with `_.defaults`; adding a third output style means adding a key there and a matching npm script.
Contributor handoff
Read `.github/CONTRIBUTING.md` first — it states the core rule that for additions or bug fixes you should only modify `lodash.js` and add tests in `test/`, and explicitly says not to regenerate `dist/` or `doc/`. That rule is in tension with `ci-dist-sync.yml`, which fails the build if `npm run build` changes `dist/`, so a change to `lodash.js` does require a rebuild and commit of `dist/lodash.js` and `dist/lodash.min.js`. The style gate is JSCS with unusual rules (`requireEarlyReturn`, no `with`, single quotes, 2-space indent, JSDoc types required), so match the surrounding code exactly. Never hand-edit `dist/*`, `doc/README.md`, or anything under `vendor/` — they are generated or vendored.
- CONTRIBUTING states the contract directly: "For additions or bug fixes you should only need to modify `lodash.js`. Include updated unit tests in the `test` directory... Don't worry about regenerating the `dist/` or `doc/` files."
- Despite that guidance, `ci-dist-sync.yml` runs `npm run build` then `git diff --exit-code dist/` and fails with an explicit "Run 'npm run build' and commit the updated dist/ files" error — so an agent editing `lodash.js` must also commit the rebuilt `dist/lodash.js` and `dist/lodash.min.js`.
- `dist/lodash.js` is currently byte-identical to `lodash.js` (the build is a plain `fs.copy`), so any `lodash.js` edit produces a mechanically predictable dist diff.
- Files an agent must read before editing, in order: `.github/CONTRIBUTING.md`, `package.json` scripts, `lodash.js` (the target region plus the `lodash.<name> =` assignment block), `fp/_mapping.js` if the change touches FP, and `threat-model.md` if the change touches `set`/`merge`/`unset`/`template`.
- Tests to run locally: `npm test` (which force-builds via `pretest`), or the faster direct `node test/test` and `node test/test-fp` once a build exists; `npm run validate` is the full gate that CI uses.
- `node test/test <path>` accepts an alternate build path as its last argument, defaulting to `../lodash.js` — this is how you point the suite at `dist/lodash.min.js` or a core build.
- The Node suite requires the previous published lodash to be installed at `node_modules/lodash/lodash.js` as `lodashStable`; if it's missing the suite prints "The stable lodash dev dependency should be at least a version behind master branch" and silently returns without running.
- Style must match JSCS: two-space indent, single quotes (double only to avoid escaping), semicolons required, `with` banned, early returns required, and JSDoc blocks needing types, param descriptions and return types.
- Naming conventions are prescribed: prefer `index`, `array`, `iteratee` over `i`, `arr`, `fn`; JSCS additionally enforces `requireCamelCaseOrUpperCaseIdentifiers`.
- An optional pre-push hook is available by creating a root `.opt-in` file containing `pre-push`, which runs `npm run validate` on push.
- Safe edit boundary — do not touch: `dist/*` (generated, and `lodash.core*` only by external lodash-cli), `doc/README.md` (docdown output), `vendor/**` (Backbone/Underscore/json2/firebug-lite), `package-lock.json` unless deliberately updating deps.
- Trap: adding an FP-visible method means touching `fp/_mapping.js` in up to five places (`aryMethod` bucket, plus any of `aliasToReal`, `remap`, `methodRearg`, `iterateeAry`, `mutate`, `skipFixed`, `skipRearg`) or the FP build and wiki will silently omit or mis-wrap it. (inferred)
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 27 | 100% |
| YAML | 8 | docs/config |
| Markdown | 7 | docs/config |
| HTML | 5 | docs/config |
| JSON | 2 | docs/config |
Start reading here
Probable source entrypoint: lib/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (21 files)
Source layout — lib/
| Path | Files |
|---|---|
lib/common/ | 5 |
lib/fp/ | 12 |
lib/main/ | 4 |
Repository structure
| Top-level path | Files |
|---|---|
lib/ | 21 |
test/ | 10 |
.github/ | 9 |
fp/ | 4 |
perf/ | 3 |
doc/ | 1 |
Docs found: README.md
Package
package.json — lodash v4.18.1, 27 declared dependencies.
asyncbenchmarkchalkcheeriocodecov.iocoverallscurl-amddocdowndojoecstaticfs-extraglob
CI & config entrypoints
README.md— Repository readme.github/workflows/renovate.yml— GitHub Actions workflow.github/workflows/ci-dist-sync.yml— GitHub Actions workflow.github/workflows/scorecards.yml— GitHub Actions workflow.github/workflows/browser-testing.yml— GitHub Actions workflow.github/workflows/codeql.yml— GitHub Actions workflow.github/workflows/ci-bun.yml— GitHub Actions workflow.github/workflows/ci-docs.yml— GitHub Actions workflow.github/workflows/ci-node.yml— GitHub Actions workflowpackage.json— npm scripts: build, build:fp, build:fp-modules, build:main, build:main-modules, doc, doc:fp, doc:site
Structural health signals
Average score 8.7/10 across 27 analyzed source files; 5 hotspots surfaced.
test/test.js— 2639 lines, score 5 (Large file, Deep nesting)test/test-fp.js— 2322 lines, score 5.5 (Large file, Deep nesting)perf/perf.js— 1978 lines, score 5.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
2b5e6f7399a72026-09-11 — ci: update actions to latest versions (#6279)0f79302eaf532026-09-09 — ci: ossf/scorecard-action update to 2.4.4 (#6278)a666ba5910642026-07-03 — docs: fix some minor docs inconsistencies (#6249)9429a4ee03052026-06-25 — ci(playwright): fix browser test flake from test timeout shorter than assertionbe2b153da4762026-06-25 — docs: clarify number-word behavior in startCase examples (#6224)