{"id":12018,"library":"shardy-mc-shard-face","title":"Sharding Utility for CI Services","description":"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.","status":"maintenance","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/joscha/ShardyMcShardFace","tags":["javascript"],"install":[{"cmd":"npm install shardy-mc-shard-face","lang":"bash","label":"npm"},{"cmd":"yarn add shardy-mc-shard-face","lang":"bash","label":"yarn"},{"cmd":"pnpm add shardy-mc-shard-face","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for automatically detecting CI parallelization parameters (e.g., current shard index and total shard count) from environment variables.","package":"ci-parallel-vars","optional":false}],"imports":[{"note":"The primary sharding function is a named export. There is no default export.","wrong":"import shardyMcShardFace from 'shardy-mc-shard-face';","symbol":"shard","correct":"import { shard } from 'shardy-mc-shard-face';"},{"note":"For CommonJS environments, destructure the named 'shard' export. This package ships with TypeScript types, but CommonJS is still supported in Node.js environments.","symbol":"shard (CommonJS)","correct":"const { shard } = require('shardy-mc-shard-face');"},{"note":"The CLI is installed as 'shardy'. Input is newline-separated to stdin, output is newline-separated to stdout. Environment variables like CI_NODE_INDEX and CI_NODE_TOTAL are crucial for its operation.","symbol":"shardy (CLI)","correct":"cat items.txt | shardy shard"}],"quickstart":{"code":"import { shard as shardyMcShardFace } from 'shardy-mc-shard-face';\n\n// Simulate CI environment variables for local testing\nprocess.env.CI_NODE_INDEX = '0'; // Current shard index (0-based)\nprocess.env.CI_NODE_TOTAL = '2'; // Total number of shards\n\nconst allItems = [\n  'test_file_A.spec.ts',\n  'test_file_B.spec.ts',\n  'test_file_C.spec.ts',\n  'test_file_D.spec.ts',\n  'test_file_E.spec.ts',\n  'test_file_F.spec.ts'\n];\n\n// Basic sharding, options are optional\nconst myShard = shardyMcShardFace(allItems);\n\nconsole.log(`Running on CI node ${process.env.CI_NODE_INDEX} of ${process.env.CI_NODE_TOTAL}`);\nconsole.log('My assigned shard:', myShard);\n\n// Example with custom options and seed for stable distribution\nconst customShard = shardyMcShardFace(allItems, {\n  throwOnEmpty: false, // Don't throw if shard is empty\n  seed: 'my-stable-seed' // Ensures same items always go to same shard\n});\n\nconsole.log('My assigned shard with custom seed:', customShard);","lang":"typescript","description":"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."},"warnings":[{"fix":"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)`.","message":"The `shard` function's last parameter changed from a string to an options map.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"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.","message":"This package relies heavily on CI environment variables (`CI_NODE_INDEX`, `CI_NODE_TOTAL`, etc.) to determine sharding parameters. If these are not set, it will default to a single shard (index 0 of 1).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"The project has not seen a new release since November 2019. While functional, active development and rapid bug fixes are unlikely.","severity":"gotcha","affected_versions":">=2.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Wrap the seed string in an options object: `shard(items, { seed: 'your-seed' });`","cause":"Attempting to pass a seed string directly as the last argument to the `shard` function in versions 2.0.0 or later.","error":"TypeError: Expected options to be an object, but got string."},{"fix":"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.","cause":"The `CI_NODE_INDEX` or `CI_NODE_TOTAL` environment variables are not correctly set or are missing, causing the library to assume a single execution node.","error":"Items are not being sharded; all items are returned in every execution."}],"ecosystem":"npm"}