array-find-index

array-find-index is a minimal ponyfill that provides the ES2015 Array.prototype.findIndex() behavior as a standalone function, for JavaScript environments that predate native support. Rather than patching the Array prototype like a polyfill would, it exposes a single function that takes the array as its first argument, followed by the predicate and an optional context, delegating straight to the native findIndex when it’s available and only running the manual fallback loop when it isn’t.

This makes it useful in libraries and tools that need consistent findIndex-style behavior across a wide range of Node.js and browser versions without silently mutating global built-ins, keeping the footprint at a single small file with no runtime dependencies.

What You Get

• A single exported function matching the native findIndex(predicate, thisArg) call signature
• Automatic delegation to native Array#findIndex when the runtime already supports it
• A manual fallback loop for environments lacking native support, with matching -1/index return semantics
• Zero runtime dependencies and a single small file (index.js)

Common Use Cases

• Polyfilling missing Array#findIndex support when targeting legacy browsers
• Providing consistent findIndex behavior across a fleet of supported Node.js versions
• Depending on it as a lightweight transitive utility inside other npm packages instead of a full polyfill library
• Avoiding prototype pollution or mutation of Array.prototype in shared codebases

Under The Hood

Architecture array-find-index is architecturally about as minimal as an npm package gets: a single index.js file (fewer than 30 lines) exports one function with no internal modules, classes, or layering. The function first checks for native Array.prototype.findIndex and delegates to it when present, only falling back to a hand-written for-loop over Object(arr) when the native method is absent. There’s no dependency injection, no internal state, and no data flow beyond the single function call — the entire ‘architecture’ is a runtime feature-detection branch. Changing or removing the fallback loop would only affect very old JavaScript engines lacking native findIndex, since the native path is always preferred when available.

Tech Stack The package is authored in plain CommonJS JavaScript with no transpilation or build step — it ships index.js directly, targeting Node.js >=0.10.0 per package.json’s engines field. The only dependency is a devDependency on ava ^0.25.0 for testing; there’s no bundler, no TypeScript, and no runtime dependencies at all. CI (.github/workflows/main.yml) runs npm install and npm test on Node.js via GitHub Actions, and the project carries a Tidelift security-contact policy (.github/security.md) but no other tooling integrations.

Code Quality Testing uses ava, with test.js covering the fallback path by explicitly unsetting Array.prototype.findIndex before asserting both a matching-element case and a no-match case — a reasonable, if minimal, test for a single-function package. Error handling is limited to one explicit TypeError thrown when the predicate argument isn’t callable, mirroring the native method’s contract. There are no type annotations (plain JS, no TypeScript or JSDoc types) and no visible ESLint/Prettier configuration in the repo, though GitHub Actions CI does run the test suite on every push and pull request.

API Design As a ponyfill rather than a polyfill, the package’s core design choice is to avoid mutating Array.prototype — instead it exports a single function taking the array as its first argument, followed by the predicate and an optional thisArg context, deliberately mirroring the native Array#findIndex(predicate, thisArg) signature so migrating to native usage later is close to a drop-in replacement. Getting started requires a single require() call and no configuration, keeping boilerplate essentially at zero. Documentation is limited to a short README with one usage example, but the API surface is small enough that this is sufficient. There’s no novel technical contribution here — the ponyfill pattern itself, referencing the ponyfill.com convention in the README, is a well-established, standard approach to shimming spec methods without global mutation.