{"id":15007705,"url":"https://github.com/RANDSUM/randsum","last_synced_at":"2025-10-30T11:31:58.930Z","repository":{"id":42984427,"uuid":"124177548","full_name":"RANDSUM/randsum-ts","owner":"RANDSUM","description":"Ergonomic Dice Rolling with Strong Typescript Support","archived":false,"fork":false,"pushed_at":"2025-01-27T23:00:27.000Z","size":3534,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-27T23:30:01.791Z","etag":null,"topics":["dice","dice-roller","dice-rolling","dice-rolling-simulator","dice-rolls","diceware","javascript","javascript-library","npm-package","npm-publish","npmjs","rollup","types","typescript","typescript-library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RANDSUM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-07T04:09:21.000Z","updated_at":"2025-01-27T22:59:40.000Z","dependencies_parsed_at":"2023-09-15T13:13:55.438Z","dependency_job_id":"b9efad7f-8b0c-4114-9199-fb428495ba30","html_url":"https://github.com/RANDSUM/randsum-ts","commit_stats":{"total_commits":700,"total_committers":5,"mean_commits":140.0,"dds":0.6228571428571428,"last_synced_commit":"f3f52680414490c8ec6614079fb55bdf2eff9d2f"},"previous_names":["randsum/randsum-ts","alxjrvs/randsum"],"tags_count":93,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RANDSUM","download_url":"https://codeload.github.com/RANDSUM/randsum-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238960849,"owners_count":19559358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dice","dice-roller","dice-rolling","dice-rolling-simulator","dice-rolls","diceware","javascript","javascript-library","npm-package","npm-publish","npmjs","rollup","types","typescript","typescript-library"],"created_at":"2024-09-24T19:13:30.660Z","updated_at":"2025-10-30T11:31:58.918Z","avatar_url":"https://github.com/RANDSUM.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"150\" height=\"150\" src=\"https://raw.githubusercontent.com/RANDSUM/randsum/refs/heads/main/icon.webp\" alt=\"Randsum Logo. A Dotted D6 rolled a 6 with the dots arranged to look like an R.\"\u003e\n  \u003ch1\u003eRandsum\u003c/h1\u003e\n  \u003ch3\u003eA comprehensive dice rolling monorepo ecosystem for rolling dice and playing games.\u003c/h3\u003e\n\n[![License](https://img.shields.io/npm/l/randsum)](https://github.com/RANDSUM/randsum/blob/main/LICENSE)\n[![CI Status](https://github.com/RANDSUM/randsum/workflows/CI/badge.svg)](https://github.com/RANDSUM/randsum/actions)\n[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat\u0026logo=bun\u0026logoColor=white)](https://bun.sh)\n[![Built with Moon](https://img.shields.io/badge/Built%20with-Moon-blue?style=flat)](https://moonrepo.dev)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript)](https://www.typescriptlang.org/)\n[![NPM Downloads](https://img.shields.io/npm/dm/@randsum/roller)](https://www.npmjs.com/package/@randsum/roller)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/RANDSUM/randsum/commits/main)\n[![Types](https://img.shields.io/badge/Types-included-blue)](https://www.npmjs.com/package/@randsum/roller)\n\n\u003c/div\u003e\n\n## 📦 Monorepo Structure\n\nThis repository contains multiple packages and applications for dice rolling and tabletop RPG mechanics:\n\n### Core Packages\n\n- **[@randsum/roller](packages/roller)** - Core dice rolling engine with advanced notation support\n- **[@randsum/blades](packages/blades)** - Blades in the Dark system mechanics\n- **[@randsum/daggerheart](packages/daggerheart)** - Daggerheart RPG system support\n- **[@randsum/fifth](packages/fifth)** - D\u0026D 5th Edition mechanics\n- **[@randsum/root-rpg](packages/root-rpg)** - Root RPG system implementation\n- **[@randsum/salvageunion](packages/salvageunion)** - Salvage Union mechanics\n\n### Applications\n\n- **[@randsum/mcp](packages/mcp)** - Model Context Protocol server for AI integration\n\nAll packages are built with TypeScript, thoroughly tested, and published to NPM with full type definitions.\n\n## 🚀 Quick Example\n\n```typescript\nimport { roll } from \"@randsum/roller\"\n\n// Simple d20 roll\nroll(20) // Returns 1-20\n// or\nroll(\"1d20\") // Returns 1-20\n\n// Complex dice notation\nroll(\"4d6L\") // Roll 4d6, drop lowest\n\n// Advantage and disadvantage\nroll(\"2d20H\") // Roll with advantage (2d20, keep highest)\nroll(\"2d20L\") // Roll with disadvantage (2d20, keep lowest)\n\nroll(\"4d6L!R{\u003c3}\") // Roll 4d6, drop lowest, reroll below 3\n```\n\nOr directly from your terminal:\n\n```bash\nnpx randsum 2d20    # Roll two twenty-sided dice\nnpx randsum 4d6L    # Character stat roll (drop lowest)\nnpx randsum 2d20H   # Roll with advantage\n```\n\n## 🛠️ Development\n\nThis monorepo uses [Moon](https://moonrepo.dev) for task orchestration and [Bun](https://bun.sh) for package management and execution.\n\n### Getting Started\n\n```bash\n# Clone the repository\ngit clone https://github.com/RANDSUM/randsum.git\ncd randsum\n\n# Install dependencies for all packages\nbun install\n\n# Build all packages\nbun moon :build\n\n# Run tests\nbun moon :test\n\n# Run type checks\nbun moon :tsCheck\n\n# Lint and format\nbun moon :lint\nbun moon :format\n```\n\n### Monorepo Workflow\n\nMoon orchestrates tasks across all packages with intelligent dependency management:\n\n**Global Tasks** (run across all packages):\n\n- `:build` - Build all packages in dependency order\n- `:test` - Run all tests with proper dependencies\n- `:lint` - Run ESLint checks across the monorepo\n- `:tsCheck` - Run TypeScript checks for all packages\n- `:ci` - Complete CI pipeline (build, test, lint, tsCheck)\n- `:lint:fix` - Run ESLint and automatically fix issues\n- `:format` - Format code using Prettier\n\n**Package-Specific Tasks**:\n\n```bash\nbun moon roller:test      # Run tests for @randsum/roller only\nbun moon blades:build     # Build @randsum/blades only\nbun moon mcp:tsCheck      # Type check the MCP server\n```\n\nMoon automatically handles inter-package dependencies, ensuring packages are built in the correct order.\n\n## 📚 Documentation\n\n### Package Documentation\n\nEach package includes comprehensive documentation:\n\n- **API Reference**: Generated TypeDoc documentation for all packages\n- **README Files**: Individual package documentation in each `packages/*/README.md`\n- **Examples**: Usage examples and integration guides\n\n### Key Resources\n\n- [Randsum Dice Notation](https://github.com/RANDSUM/randsum/blob/main/packages/roller/RANDSUM_DICE_NOTATION.md) - A guide for using [Dice Notation](https://en.wikipedia.org/wiki/Dice_notation) with `randsum`\n- [Sophie's Dice Notation](https://sophiehoulden.com/dice/documentation/notation.html) - a great dice notation guide that helped me along the way\n- [\\_why's poignant guide to ruby](https://poignant.guide/) - \\_why not?\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to your branch\n5. Open a Pull Request\n\n---\n\n## Why did you make this?\n\nSometime around 2012, I decided I wanted to learn to program. I had installed ruby on the best laptop six-hundred dollars could buy, set to make a dice roller as an easy first project.\n\nI spent an easy 30 minutes trying to figure out how to make `rand(n)` return `1...n` instead of `0...(n-1)`.\n\nWhen I found the answer, I laughed and laughed. I've been chasing that high ever since.\n\n---\n\n## LLM Statement\n\nI have used LLM (\"AI\") tools while making this library. Unless I am mis-remembering, it was entirly Claude Sonnet, used through the tool Augment Code.\n\nI love this thing we call programming. It seems as if this tech might be a part of it moving forward.\n\nYou will find the extent of my comfort with these tools in this project, for it is the closest thing I have on this earth to a life's work.\n\nIs the use of this profane? Is my work perma-tainted? I don't know. The type-ahead suggests I say \"I am not ashamed\", and so I remain comforted that it is not yet able to accurately imitate my mind.\n\nCheck the git history of this paragraph (and README, where it used to live.) for a makeshift changelog of my evolving feelings on the subject.\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with 👹 by \u003ca href=\"https://github.com/RANDSUM\"\u003eRANDSUM\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRANDSUM%2Frandsum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRANDSUM%2Frandsum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRANDSUM%2Frandsum/lists"}