{"_id":"@bardsballad/cadence","_rev":"2-93867389301782ca81453d5a7978c87e","name":"@bardsballad/cadence","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@bardsballad/cadence","version":"0.1.0","keywords":["expression","safe","sandbox","ttrpg"],"author":"","license":"MIT","_id":"@bardsballad/cadence@0.1.0","maintainers":[{"name":"kingcosmic","email":"KingCosmicDev@gmail.com"}],"dist":{"shasum":"7bf7c1a3ff80ec0da67e8e563bb36f1288789563","tarball":"https://registry.npmjs.org/@bardsballad/cadence/-/cadence-0.1.0.tgz","fileCount":21,"integrity":"sha512-HVC89qR1vo2OC/UtxCoLcUmWuqZbh//dMmsVFw4EciboVsC0JcOs1uUZ9YxSDjFFYgImbWbwZG39j1uSzwnUwA==","signatures":[{"sig":"MEYCIQD5PeeDaMPj4YOIEcYy4YCYsxSp3srxfqCOGGQz+wCtYQIhAJEVe9LL6pE94ySsMnB8EkAw2tu2WqJaBJjuuq76/mRr","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24398},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"test":"jest","build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"kingcosmic","email":"KingCosmicDev@gmail.com"},"_npmVersion":"10.8.3","description":"Cadence: a safe, deterministic expression engine for user-generated content.","directories":{},"_nodeVersion":"24.11.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.6.3","@types/jest":"^29.5.12"},"_npmOperationalInternal":{"tmp":"tmp/cadence_0.1.0_1766806811029_0.4199647219473681","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bardsballad/cadence","version":"0.1.1","description":"Cadence: a safe, deterministic expression engine for user-generated content.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","prepublishOnly":"npm run build","test":"jest"},"keywords":["expression","safe","sandbox","ttrpg"],"author":"","license":"MIT","publishConfig":{"access":"public"},"devDependencies":{"@types/jest":"^29.5.12","jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.6.3"},"_id":"@bardsballad/cadence@0.1.1","gitHead":"4cbd88362e90931101638a08fca2faf0fe465d66","_nodeVersion":"24.11.1","_npmVersion":"10.8.3","dist":{"integrity":"sha512-3WxLedpaPw179yOrKjPNretUkmgpDnkvj+fWsa+1NeZlIQlR72GXVp3KcNUfoPomDK2HiwQO+rceAW+pv5gRTw==","shasum":"7efe960f4994cb4cabdc4669d3ac7f159f001345","tarball":"https://registry.npmjs.org/@bardsballad/cadence/-/cadence-0.1.1.tgz","fileCount":23,"unpackedSize":29725,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHIWRyA2dEZ/vvjvQE0hvoUh3OFYM540CHtD8nKYmPTmAiEAnbbtkKJhfR5ToaCAK+S3uOzx2Gx+2TpDGt4HeUj7Yu8="}]},"_npmUser":{"name":"kingcosmic","email":"KingCosmicDev@gmail.com"},"directories":{},"maintainers":[{"name":"kingcosmic","email":"KingCosmicDev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cadence_0.1.1_1766819893676_0.8997349187860053"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-27T03:40:10.921Z","modified":"2025-12-27T07:18:14.139Z","0.1.0":"2025-12-27T03:40:11.171Z","0.1.1":"2025-12-27T07:18:13.903Z"},"license":"MIT","keywords":["expression","safe","sandbox","ttrpg"],"description":"Cadence: a safe, deterministic expression engine for user-generated content.","maintainers":[{"name":"kingcosmic","email":"KingCosmicDev@gmail.com"}],"readme":"# Cadence\r\n\r\nA safe, deterministic expression engine for user-generated content.\r\n\r\nCadence is a lightweight, sandboxed expression evaluator designed for TTRPG systems and other applications that need to safely execute user-defined calculations without the risks of arbitrary code execution.\r\n\r\n## Features\r\n\r\n- **Deterministic Evaluation**: Consistent results for the same inputs every time\r\n- **Safe Sandbox**: No file system access, no arbitrary function execution, no side effects\r\n- **Type-Safe**: Built with TypeScript for robust type checking\r\n- **Array Operations**: Built-in helpers for sum, count, min, max, avg, any, all\r\n- **Math Functions**: Support for floor, ceil, abs, round, and more\r\n- **Conditional Logic**: Ternary operators and boolean operations\r\n- **Variable Binding**: Assign intermediate results with named variables\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @bardsballad/cadence\r\n```\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport { runCadence } from '@bardsballad/cadence';\r\n\r\nconst program = `\r\n  floor((score - 10) / 2) [modifier];\r\n  modifier < 0 ? \"-\" : \"+\" [sign];\r\n  sign + abs(modifier)\r\n`;\r\n\r\nconst result = runCadence(program, { score: 14 });\r\nconsole.log(result); // \"+2\"\r\n```\r\n\r\n## Syntax\r\n\r\n### Basic Expressions\r\n\r\n```typescript\r\n// Arithmetic\r\n2 + 3 * 4\r\n10 - 5\r\n20 / 4\r\n3 * 3\r\n\r\n// Comparison\r\nx > 5\r\ny <= 10\r\na === b\r\nc !== d\r\n\r\n// Boolean Logic\r\ntrue && false\r\ntrue || false\r\n!condition\r\n```\r\n\r\n### Variable Binding\r\n\r\nUse square brackets to bind intermediate results:\r\n\r\n```typescript\r\nscore - 10 [adjusted];\r\nadjusted / 2 [halved];\r\nfloor(halved)\r\n```\r\n\r\n### Conditionals\r\n\r\nTernary operator for conditional evaluation:\r\n\r\n```typescript\r\nx > 5 ? \"big\" : \"small\"\r\nscore >= 20 ? 10 : score >= 10 ? 5 : 0\r\n```\r\n\r\n### Array Operations\r\n\r\n```typescript\r\n// Available helpers\r\nsum([1, 2, 3])              // 6\r\ncount([a, b, c])            // 3\r\nmin([5, 2, 8])              // 2\r\nmax([5, 2, 8])              // 8\r\navg([10, 20, 30])           // 20\r\nany([false, false, true])   // true\r\nall([true, true, false])    // false\r\n```\r\n\r\n### Math Functions\r\n\r\n```typescript\r\nfloor(3.7)      // 3\r\nceil(3.2)       // 4\r\nround(3.5)      // 4 (banker's rounding)\r\nabs(-5)         // 5\r\n```\r\n\r\n## API\r\n\r\n### `runCadence(program: string, input: Record<string, any>): any`\r\n\r\nExecutes a Cadence program with the provided input variables.\r\n\r\n**Parameters:**\r\n- `program`: The expression string to evaluate\r\n- `input`: An object containing variables available to the program\r\n\r\n**Returns:** The result of evaluating the final expression\r\n\r\n**Example:**\r\n\r\n```typescript\r\nconst damage = runCadence(\r\n  `base_damage + (strength_modifier > 0 ? strength_modifier : 0)`,\r\n  { base_damage: 8, strength_modifier: 3 }\r\n); // 11\r\n```\r\n\r\n## Examples\r\n\r\n### D&D Ability Modifier Calculation\r\n\r\n```typescript\r\nimport { runCadence } from '@bardsballad/cadence';\r\n\r\nconst modifier = runCadence(\r\n  `floor((ability_score - 10) / 2)`,\r\n  { ability_score: 16 }\r\n); // 3\r\n```\r\n\r\n### Damage Calculation with Modifiers\r\n\r\n```typescript\r\nconst damage = runCadence(\r\n  `base_damage [d];\r\n   d + strength_mod + (is_critical ? d : 0)`,\r\n  { base_damage: 6, strength_mod: 2, is_critical: true }\r\n); // 14\r\n```\r\n\r\n### Complex Conditional Pricing\r\n\r\n```typescript\r\nconst price = runCadence(\r\n  `base_price [b];\r\n   quantity > 100 ? b * 0.9 : quantity > 10 ? b * 0.95 : b`,\r\n  { base_price: 100, quantity: 50 }\r\n); // 95\r\n```\r\n\r\n## Safety\r\n\r\nCadence enforces strict safety boundaries:\r\n\r\n- **No Global Access**: Variables must be explicitly passed via the `input` object\r\n- **No Function Definition**: Users cannot define custom functions\r\n- **No Mutations**: All operations are pure and side-effect free\r\n- **No External Calls**: No file system, network, or environment access\r\n- **Type Validation**: Helper functions validate argument types\r\n\r\nThis makes Cadence suitable for user-facing expression editors where you need to prevent malicious or accidental code execution.\r\n\r\n## Development\r\n\r\n### Build\r\n\r\n```bash\r\nnpm run build\r\n```\r\n\r\n### Test\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please ensure all tests pass before submitting pull requests.\r\n\r\n```bash\r\nnpm test\r\nnpm run build\r\n```\r\n","readmeFilename":"README.md"}