WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

stdlib is a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computation. It provides a comprehensive collection of robust, high performance libraries for mathematics, statistics, data processing, streams, and more. The library is fully decomposable, allowing individual packages to be consumed independently.

Architecture

Monorepo Structure

stdlib is organized as a monorepo containing thousands of individual packages. The key architecture:

Package System: Each package in lib/node_modules/@stdlib/ is independently consumable
Namespace Organization: Packages are organized by namespace (e.g., @stdlib/math, @stdlib/stats, @stdlib/array)
Package Naming: Internal paths use / (e.g., @stdlib/math/base/special/sin), but when installed as individual npm packages, use - (e.g., @stdlib/math-base-special-sin)
Top-level Namespaces: Major categories include math, stats, array, ndarray, random, assert, utils, string, and many more

Directory Organization

bin/                 Executable binaries and CLI tools
deps/                External library dependencies  
dist/                Distributable files
docs/                Top-level documentation
etc/                 Configuration files
examples/            Top-level library examples
lib/                 Library source code (main implementation area)
  node_modules/      All stdlib packages under @stdlib/
    @stdlib/         Package implementations
      _tools/        Internal development tools
      math/          Math functions and operations
      stats/         Statistical functions
      array/         Array utilities
      ndarray/       N-dimensional array support
      random/        Random number generation
      [...]          Many other namespaces
test/                Top-level tests
tools/               Development utilities (make infrastructure, scripts)
  make/              Makefile infrastructure
  scripts/           Build and maintenance scripts
workshops/           Educational workshops

Package Structure

Each package follows a consistent structure:

benchmark/           Performance benchmarks
bin/                 CLI (if applicable)
docs/                Package documentation
  repl.txt           REPL help text (required)
  types/             TypeScript declarations
examples/            Usage examples
etc/                 Configuration files
lib/                 Implementation
  index.js           Main export (required)
  main.js            Primary implementation (common pattern)
src/                 Native code (C/C++/Fortran) if applicable
test/                Unit tests (required)
package.json         Package metadata (required)
README.md            Main documentation (required)

Common Development Commands

Testing

# Run all tests
make test

# Run tests for specific package/path (use regex pattern)
make TESTS_FILTER=".*/math/base/special/sin/.*" test

# Run tests with coverage
make test-cov
make view-cov

# Run tests for a specific package pattern
make TESTS_FILTER=".*/ndarray/.*" test

# Run tool tests (for code in tools/ directory)
make tools-test
make tools-test-cov

Important: In zsh and similar shells, wrap filter patterns in quotes:

make TESTS_FILTER=".*/pattern/.*" test

Benchmarks

# Run all benchmarks
make benchmark

# Run benchmarks for specific package/path
make BENCHMARKS_FILTER=".*/math/base/special/.*" benchmark

Examples

# Run all examples
make examples

# Run examples for specific package/path
make EXAMPLES_FILTER=".*/math/base/special/sin/.*" examples

Linting

# Lint all files
make lint

# Lint specific file types
make lint-javascript
make lint-markdown
make lint-filenames
make lint-pkg-json

Building and Installation

# Install all dependencies
make install

# Install Node.js dependencies specifically
make install-node-modules

# Initialize development environment (Git hooks, etc.)
make init

# Clean build artifacts
make clean

REPL

# Launch the stdlib REPL (with integrated help)
make repl

Other Useful Commands

# List all packages
make list-pkgs

# List all source files matching a pattern
make SOURCES_FILTER=".*/math/.*" list-sources

# Search for code annotations (TODO, FIXME, etc.)
make notes

# View help for all make targets
make help

Development Workflow

For New Package Development

README First: Write the README.md documenting the API and usage
Create package.json: Define package metadata and keywords
Write examples: Create examples/index.js matching the main README example
Implement: Write the implementation in lib/
Write benchmarks: Create benchmarks in benchmark/
Write tests: Achieve 100% code coverage with comprehensive unit tests in test/
REPL documentation: Write docs/repl.txt following the REPL text guide
TypeScript declarations: Add docs/types/index.d.ts with type definitions and docs/types/test.ts for type tests
CLI (if applicable): Implement command-line interface in bin/

Testing Individual Packages

When working on a specific package, use filter patterns to target just that package:

# For a package at lib/node_modules/@stdlib/math/base/special/sin
make TESTS_FILTER=".*/math/base/special/sin/.*" test
make BENCHMARKS_FILTER=".*/math/base/special/sin/.*" benchmark
make EXAMPLES_FILTER=".*/math/base/special/sin/.*" examples

The pattern matches the absolute path, so include .* before and after your target path segment.

Code Organization Conventions

Consistency is paramount: Study existing packages before creating new ones
Modular design: Each package should have a single, well-defined purpose
Minimal surface area: Keep APIs focused and minimal
Fallbacks: For native add-ons, always provide JavaScript fallbacks
100% test coverage: All packages must have complete test coverage
Documentation: Every function requires comprehensive documentation

TypeScript

All packages include TypeScript declaration files (docs/types/index.d.ts)
Type declarations are tested with docs/types/test.ts
JSDoc types don't map 1-to-1 with TypeScript types; consult existing packages

Native Add-ons

Native implementations (C/C++/Fortran) go in src/
Always provide JavaScript fallback implementations
Native add-ons use binding.gyp for compilation configuration
Optional dependencies on compilers (gcc, gfortran, etc.)

Key Implementation Patterns

Package Exports (lib/index.js)

The main index.js typically doesn't contain implementation but imports from other files:

var main = require( './main.js' );
module.exports = main;

This allows for environment-specific exports and conditional loading of native implementations.

Native vs JavaScript Fallback

Packages with native implementations often check for availability:

var native = require( './native.js' );
var fallback = require( './main.js' );

module.exports = ( native ) ? native : fallback;

Package Naming Convention

Internal reference: @stdlib/math/base/special/sin
As npm package: @stdlib/math-base-special-sin
In code imports: Use the internal / format when working within the monorepo

Testing Requirements

100% code coverage is mandatory for all packages
Tests must cover:
- All code paths and branches
- Input validation and error conditions
- Edge cases and boundary conditions
- All option combinations
- Type checking and assertions

Troubleshooting

Build Issues

If you encounter build conflicts with dependencies:

make clean
make install

Zsh Path Expansion

In zsh, environment variables may require quotes to prevent path expansion:

# Instead of:
make TESTS_FILTER=.*/pattern/.* test

# Use:
make TESTS_FILTER=".*/pattern/.*" test

Git Performance

If your terminal shows git status in the prompt and it's slow, disable dirty state display:

# Bash
git config bash.showDirtyState false

# Zsh
git config --add oh-my-zsh.hide-dirty 1

Project Documentation

Development guide: docs/contributing/development.md
Package guide: docs/contributing/packages.md
Contributing guide: CONTRIBUTING.md
Style guides: Referenced in contributing documentation
REPL text guide: docs/contributing/repl_text.md

Important Notes for AI Agents

Filter Syntax: Always use the pattern ".*/path/segment/.*" for TESTS_FILTER, BENCHMARKS_FILTER, and EXAMPLES_FILTER
Never skip tests: Always run tests after making changes to verify correctness
Consistency over innovation: Follow existing patterns in the codebase rather than introducing new patterns
Complete packages: When creating packages, include all required components (README, tests, examples, benchmarks, docs/repl.txt, TypeScript declarations)
License headers: All files require Apache-2.0 license headers
EditorConfig: The project uses EditorConfig for consistent formatting

batpigandme/tl-stdlib-warp.md

Select an option

No results found