ShardyMcShardFace is a JavaScript/TypeScript utility library designed to efficiently shard arrays of items across multiple parallel processes, primarily for Continuous Integration (CI) environments. It leverages standard CI environment variables like `CI_NODE_INDEX` and `CI_NODE_TOTAL` (via the `ci-parallel-vars` dependency) to determine the current shard and total shard count, distributing items as evenly as possible. The current stable version is 2.1.0, released in November 2019. Since then, the project appears to be in a maintenance-only state, with no new releases in over five years. Key features include stable, random-seeded item distribution, graceful handling of scenarios where the item count is less than the total shard count, and full TypeScript support, ensuring type safety. It offers both a programmatic API for direct integration into JavaScript/TypeScript applications and a command-line interface for simple shell scripting. Its primary differentiator is its direct, opinionated integration with common CI parallelization parameters, simplifying the setup for distributed test suites or build steps.
npm install shardy-mc-shard-faceVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to programmatically shard an array of items using `shardy-mc-shard-face`. It simulates CI environment variables and shows both basic usage and how to apply custom options like a stable seed.
If you were passing a string as the last argument (e.g., for a seed), you must now pass an object `{ seed: 'your-seed' }` or similar. Refer to the updated function signature: `shardyMcShardFace(items, options)`.Ensure that your CI system correctly sets these environment variables. For local development or testing, you may need to manually set `process.env.CI_NODE_INDEX` and `process.env.CI_NODE_TOTAL` or use the `concurrency` option within the API if available in newer versions.
Assess the stability and existing features carefully. Consider contributing fixes or new features if needed, or fork the repository. Be aware that future JavaScript/TypeScript ecosystem changes might not be immediately supported.
Wrap the seed string in an options object: `shard(items, { seed: 'your-seed' });`Verify that your CI environment or local setup correctly defines `CI_NODE_INDEX` and `CI_NODE_TOTAL` (e.g., `process.env.CI_NODE_INDEX = '0'; process.env.CI_NODE_TOTAL = '2';`). The library uses `ci-parallel-vars` to detect these.