Implement IntToUuid Specification

Author: andysnell

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Node.js ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ["20", "22", "24"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test
+
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+      - run: npm ci
+      - run: npm run build

.gitignore

@@ -2,3 +2,5 @@ node_modules/
 dist/
 *.tgz
 .DS_Store
+/.idea
+/.remember

.node-version

@@ -1 +1 @@
-22
+24

.prettierignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+package-lock.json

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-25
+
+### Added
+
+- Initial release
+- `IntegerId` value object with validation and immutability
+- `encode()` function to convert IntegerId to Version 8 UUID
+- `decode()` function to convert Version 8 UUID back to IntegerId
+- Full test suite with 36 official test vectors
+- Dual ESM/CJS output via tsup
+
+[1.0.0]: https://github.com/wickedbyte/int-to-uuid-ts/releases/tag/v1.0.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,135 @@
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all
+individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics,
+neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or
+religion, national or social origin, socio-economic position, level of education, or other status. The same privileges
+of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive
+behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture,
+background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared
+values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are
+violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any
+   clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of
+   people.
+3. **Stereotyping or discrimination.** Characterizing anyone's personality or behavior on the basis of immutable
+   identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or
+   purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their
+   permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade
+   enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the
+   community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other
+   restricted behaviors.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict
+represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help
+avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, **email
+[security@wickedbyte.com](mailto:security@wickedbyte.com) or use
+the [wickedbyte.com contact form](https://wickedbyte.com/contact).** Please be sure to indicate that you are reporting a
+code of conduct violation in your message.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They
+will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing
+witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as
+possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried
+out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon
+resolution.
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following
+enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals
+involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be
+skipped.
+
+1. Warning
+   1. Event: A violation involving a single incident or series of incidents.
+   2. Consequence: A private, written warning from the Community Moderators.
+   3. Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking
+      clarification on expectations.
+2. Temporarily Limited Activities
+   1. Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a
+      more serious violation.
+   2. Consequence: A private, written warning with a time-limited cooldown period designed to underscore the
+      seriousness of the situation and give the community members involved time to process the incident. The cooldown
+      period may be limited to particular communication channels or interactions with particular community members.
+   3. Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and
+      impact, and being thoughtful about re-entering community spaces after the period is over.
+3. Temporary Suspension
+   1. Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a
+      single serious violation.
+   2. Consequence: A private written warning with conditions for return from suspension. In general, temporary
+      suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3. Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for
+      return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4. Permanent Ban
+   1. Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or
+      a violation so serious that the Community Moderators determine there is no way to keep the community safe with
+      this person as a member.
+   2. Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent
+      bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working
+      through other remedies has failed to change the behavior.
+   3. Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their
+discretion and judgment, in keeping with the best interests of our community.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing
+the community in public or other spaces. Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available
+at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy
+of this license,
+visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ
+at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided
+at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional
+enforcement and community guideline resources can be found
+at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement
+ladder was inspired by the work of [Mozilla's code of conduct team](https://github.com/mozilla/inclusion).

CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+Contributions are welcome. This project accepts pull requests on [GitHub][github].
+
+## Communication Channels & Reporting Bugs
+
+You can find help and discussion at the project's [GitHub Issues page][issues]. Please use the issue tracker to report
+any bugs found with this project.
+
+⚠️ _**ATTENTION!!!** DO NOT include passwords or other sensitive information in your bug report._
+
+When submitting a bug report, please include enough information to reproduce the bug. A good bug report includes the
+following sections:
+
+- **Description**: Provide a short and clear description of the bug.
+
+- **Steps to Reproduce**: Provide steps to reproduce the behavior you are experiencing. Please try to keep this as short
+  as possible. If able, create a reproducible script outside any framework you are using. This will help us to
+  quickly debug the issue.
+
+- **Expected Behavior**: Provide a short and clear description of what you expect to happen.
+
+- **Screenshots or Other Output**: If applicable, add screenshots or program output to help explain your problem.
+
+- **Environment Details**: Provide details about the system where you're using this package, such as Node.js version and
+  operating system.
+
+- **Additional Context**: Provide any additional context that may help us debug the problem.
+
+## Fixing Bugs
+
+This project welcomes pull requests to fix bugs!
+
+If you see a bug report that you'd like to fix, please feel free to do so. Following the directions and guidelines
+described in the "Adding New Features" section below, you may create bugfix branches and send pull requests.
+
+## Adding New Features
+
+If you have an idea for a new feature, it's a good idea to check out the [issues][] or active [pull requests][] first to
+see if anyone is already working on the feature. If not, feel free to submit an issue first, asking whether the feature
+is beneficial to the project. This will save you from doing a lot of development work only to have your feature
+rejected. We don't enjoy rejecting your hard work, but some features don't fit with the goals of the project.
+
+When you do begin working on your feature, here are some guidelines to consider:
+
+- Your pull request description should clearly detail the changes you have made. We will use this description to update
+  the CHANGELOG. If there is no description, or it does not adequately describe your feature, we may ask you to update
+  the description.
+- All pull requests must comply with the project coding standard (see below). Please ensure your code does, too. _Hint:
+  run `npm run lint` to check._
+- Please **write tests** for any new features you add.
+- Please **ensure that tests pass** before submitting your pull request. `wickedbyte/int-to-uuid-ts` automatically runs
+  tests for pull requests. However, running the tests locally will help save time. _Hint: run `npm test`._
+- **Use topic/feature branches.** Please do not ask to pull from your main branch. - For more information,
+  see "[Understanding the GitHub flow][gh-flow]."
+- **Submit one feature per pull request.** If you have multiple features you wish to submit, please break them into
+  separate pull requests.
+
+## Developing
+
+To develop this project, you will need [Node.js](https://nodejs.org) 20 or greater and [npm](https://www.npmjs.com).
+
+After cloning this repository locally, execute the following commands:
+
+```bash
+cd /path/to/repository
+npm install
+npm test
+```
+
+The full suite of code quality tools can be run with:
+
+```bash
+npm run typecheck && npm run lint && npm test
+```
+
+### Static Analysis
+
+This project uses [TypeScript](https://www.typescriptlang.org) for static type checking. You may run type checking
+manually across the whole codebase with the following command:
+
+```bash
+# Static analysis
+npm run typecheck
+```
+
+### Coding Standards
+
+This project uses [ESLint](https://eslint.org) for linting and [Prettier](https://prettier.io) for code formatting.
+
+```bash
+# Run the code standards linter
+npm run lint
+
+# Attempt to auto-fix coding standards issues
+npm run lint -- --fix
+
+# Run the code formatter
+npm run format
+```
+
+### Running Tests
+
+The following must pass before we will accept a pull request. If this does not pass, it will result in a complete build
+failure. Before you can run this, be sure to `npm install`.
+
+To run all the tests and coding standards checks, execute the following from the command line, while in the project root
+directory:
+
+```
+npm test
+```
+
+[github]: https://github.com/wickedbyte/int-to-uuid-ts
+[issues]: https://github.com/wickedbyte/int-to-uuid-ts/issues
+[pull requests]: https://github.com/wickedbyte/int-to-uuid-ts/pulls
+[gh-flow]: https://guides.github.com/introduction/flow/

LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2025-2026 WickedByte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.