{"id":22326069,"url":"https://github.com/randsum/randsum","last_synced_at":"2026-02-16T06:03:23.726Z","repository":{"id":42984427,"uuid":"124177548","full_name":"RANDSUM/randsum","owner":"RANDSUM","description":"A flexible, type-safe dice rolling ecosystem written in Typescript","archived":false,"fork":false,"pushed_at":"2026-02-01T07:32:13.000Z","size":5454,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-01T16:21:33.315Z","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":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-03-07T04:09:21.000Z","updated_at":"2026-02-01T07:32:15.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","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","randsum/randsum","randsum/-randsum"],"tags_count":103,"template":false,"template_full_name":null,"purl":"pkg:github/RANDSUM/randsum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RANDSUM","download_url":"https://codeload.github.com/RANDSUM/randsum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RANDSUM%2Frandsum/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29501368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T05:57:17.024Z","status":"ssl_error","status_checked_at":"2026-02-16T05:56:49.929Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-12-04T02:15:28.383Z","updated_at":"2026-02-16T06:03:23.721Z","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[![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/discord-bot](apps/discord-bot)** - Discord bot with dice rolling capabilities using discord.js and Bun\n- **[@randsum/site](apps/site)** - Documentation and marketing website built with Astro\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// Argument types: number, notation string, or options object\nroll(20) // Number: 1d20 (returns 1-20)\nroll(\"1d20\") // Notation: same as above\nroll({ sides: 20, quantity: 1 }) // Object: same as above\n\n// Complex dice notation\nroll(\"4d6L\") // Roll 4d6, drop lowest\n\n// Options object (equivalent to 4d6L)\nroll({ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } })\n\n// Advantage and disadvantage\nroll(\"2d20H\") // Roll with advantage (2d20, keep highest)\nroll(\"2d20L\") // Roll with disadvantage (2d20, keep lowest)\n\n// Multiple arguments: combine rolls\nroll(\"1d20+5\", \"2d6+3\") // Attack roll + damage roll\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 [Bun](https://bun.sh) for package management, building, and task 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 (roller is built first, then others)\nbun run build\n\n# Run tests\nbun run test\n\n# Run type checks\nbun run typecheck\n\n# Lint and format\nbun run lint\nbun run format\n```\n\n### Monorepo Workflow\n\nBun's workspace features handle tasks across all packages with automatic dependency management:\n\n**Global Tasks** (run across all packages):\n\n- `bun run build` - Build all packages in dependency order (roller first, then others)\n- `bun run test` - Run all tests\n- `bun run lint` - Run ESLint checks across the monorepo\n- `bun run typecheck` - Run TypeScript checks for all packages\n- `bun run check:all` - Complete CI pipeline (lint, format check, typecheck, test)\n- `bun run fix:all` - Run ESLint with auto-fix and format code\n- `bun run format` - Format code using Prettier\n\n**Package-Specific Tasks**:\n\n```bash\nbun run --filter @randsum/roller test      # Run tests for @randsum/roller only\nbun run --filter @randsum/blades build     # Build @randsum/blades only\nbun run --filter @randsum/mcp typecheck    # Type check the MCP server\n```\n\n**Site-Specific Tasks**:\n\n```bash\nbun run site:build    # Build the documentation site\nbun run site:dev       # Start the development server\nbun run site:preview   # Preview the production build locally\n```\n\nBun automatically handles inter-package dependencies through workspace linking, 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### Website Deployment\n\nThe documentation site (`@randsum/site`) is automatically deployed to:\n\n- **Netlify**: Configured via `apps/site/netlify.toml` and deployed on push to main\n- **GitHub Pages (Repository)**: Deployed to the `gh-pages` branch via GitHub Actions\n- **GitHub Pages (Organization)**: Deployed to `randsum.github.io` repository via GitHub Actions\n\nAll deployments are triggered automatically on push to the `main` branch. The site build is included in the CI pipeline via `check:all`.\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\nThough this project predates the existence of Large learning machines by a clean decade, since their popularization I have used LLM (so-called \"AI\") tools while making this library. I've used a collection of different tools or models - I prefer the Claude collection of models, though I've played with a lot of it. I spent a lot of time with Augment, then Cursor, now I dance between Claude and Cursor and staring in the mirror wondering what happened.\n\nIs the use of this profane? Is my work perma-tainted? I don't know. The type-ahead (powered by LLM's) suggests I say \"I am not ashamed\", and so I remain comforted that it is not yet able to accurately imitate my mind.\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, with programming (\"what the machines do for me\") is the closest thing I have to a craft. One grandfather was an engineer, the other a bricklayer. In my career thus far, I have been blessed to be some combination of both.\n\n\u003e You can be grateful for the efficiency and still mourn what it cost. You can use the tools every day and still feel the weight of what they’ve changed about your craft, your career, your sense of what it means to be good at this.The code was never the point, maybe. But for a lot of us, it felt like it was. And that feeling doesn’t just disappear because the tools got better.\n\n- Dave Kiss, [Stop Calling it Vibe Coding](https://davekiss.com/blog/agentic-coding/)\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"}