diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..8c52ff9 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,12 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_style = space +indent_size = 2 +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..82095e9 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Default owner for everything in the repository +* @SahinurDEV diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..a4dc8a4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,81 @@ +name: Bug report +description: Report something that is not working as expected +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please search + [existing issues](https://github.com/SahinurDEV/ForgeData/issues?q=is%3Aissue) first. + **Security vulnerabilities must be reported privately** — see + [SECURITY.md](https://github.com/SahinurDEV/ForgeData/blob/main/SECURITY.md). + - type: textarea + id: description + attributes: + label: Describe the bug + description: A clear and concise description of what the bug is. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: Code (or CLI command) that reproduces the problem. Include the seed and locale if relevant. + render: ts + placeholder: | + import { ForgeData } from "forgedatajs"; + const forge = new ForgeData({ seed: 42, locale: "en" }); + console.log(forge.person.fullName()); + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include the full error message / stack trace if there is one. + validations: + required: true + - type: dropdown + id: entry + attributes: + label: Which part of ForgeData? + multiple: true + options: + - Core (forgedatajs) + - Zod integration (forgedatajs/zod) + - React integration (forgedatajs/react) + - CLI (forgedata) + - Locales + - Documentation / website + validations: + required: true + - type: input + id: version + attributes: + label: forgedatajs version + placeholder: "e.g. 0.2.2 (npm ls forgedatajs)" + validations: + required: true + - type: input + id: runtime + attributes: + label: Runtime and version + placeholder: "e.g. Node.js 22.11, Bun 1.1, Deno 2.0, Chrome 130" + validations: + required: true + - type: input + id: os + attributes: + label: Operating system + placeholder: "e.g. macOS 15, Ubuntu 24.04, Windows 11" + - type: textarea + id: context + attributes: + label: Additional context + description: Bundler, TypeScript version, zod/react versions, or anything else that might help. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..68ac44b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Questions and ideas (GitHub Discussions) + url: https://github.com/SahinurDEV/ForgeData/discussions + about: Ask usage questions, share ideas and show what you built with ForgeData. + - name: Documentation + url: https://sahinurdev.github.io/ForgeData/docs.html + about: Getting started, API reference, React guide, CLI reference and Faker.js migration guide. + - name: Report a security vulnerability + url: https://github.com/SahinurDEV/ForgeData/security/advisories/new + about: Please report security issues privately, not as public issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..064a1b4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,53 @@ +name: Feature request +description: Suggest a new generator, locale, option or integration +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for the suggestion! For open-ended ideas or questions, consider starting a + [discussion](https://github.com/SahinurDEV/ForgeData/discussions) instead. + - type: textarea + id: problem + attributes: + label: Problem / motivation + description: What are you trying to do, and why is it hard or impossible today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the API you would like. Example code is very welcome. + render: ts + placeholder: | + forge.location.streetAddress(); // "221B Baker Street" + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Workarounds you use today (e.g. forge.define(...)) or how other libraries solve this. + - type: dropdown + id: area + attributes: + label: Area + multiple: true + options: + - New generator / module + - New locale + - Zod integration + - React integration + - CLI + - Documentation / website + - Tooling / DX + - Other + validations: + required: true + - type: checkboxes + id: contribute + attributes: + label: Contribution + options: + - label: I would be willing to open a pull request for this diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..b82bd5c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,29 @@ + + +## Summary + + + +Closes # + +## Type of change + +- [ ] `feat` — new feature (minor release) +- [ ] `fix` — bug fix (patch release) +- [ ] `docs` / `chore` / `test` / `refactor` / `ci` — no release +- [ ] Breaking change (`!` in the title or a `BREAKING CHANGE:` footer — major release) + +## Checklist + +- [ ] The PR title follows [Conventional Commits](https://www.conventionalcommits.org/) +- [ ] `npm run preflight` passes locally (lint, typecheck, 100%-coverage tests, build) +- [ ] `npm run format:check` passes +- [ ] Tests were added/updated for every new code path +- [ ] Docs were updated if behaviour changed (`README.md`, `docs/docs.html`) +- [ ] No new runtime dependencies, and no Node-only APIs in `src/` diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..3ff7cc9 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,8 @@ +dist +coverage +node_modules +docs/dist +package-lock.json +docs/package-lock.json +# Generated by semantic-release +CHANGELOG.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..50a6c07 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,130 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a +harassment-free experience for everyone, regardless of age, body size, visible or invisible +disability, ethnicity, sex characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or +sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and +healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the + experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their + explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior +and will take appropriate and fair corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, +code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and +will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is +officially representing the community in public spaces. Examples of representing our community +include using an official e-mail address, posting via an official social media account, or acting as +an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community +leaders responsible for enforcement, the project maintainer +[@SahinurDEV](https://github.com/SahinurDEV), privately through either of these channels: + +- GitHub's private reporting: + [open a private report](https://github.com/SahinurDEV/ForgeData/security/advisories/new) on this + repository and mark it as a Code of Conduct report (this channel is visible only to the + maintainer), or +- the contact options listed on the maintainer's GitHub profile, + [github.com/SahinurDEV](https://github.com/SahinurDEV). + +You can also use GitHub's +[report abuse / report content](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) +feature to report content directly to GitHub. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any +incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for +any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or +unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the +nature of the violation and an explanation of why the behavior was inappropriate. A public apology +may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people +involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified +period of time. This includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate +behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the +community for a specified period of time. No public or private interaction with the people involved, +including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this +period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including +sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement +of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f9c2083 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,146 @@ +# Contributing to ForgeData + +Thanks for your interest in improving ForgeData! Bug reports, docs fixes, new generators, new +locales and tooling improvements are all welcome. This guide explains how to get set up and what we +look for in a pull request. + +By participating in this project you agree to abide by our [Code of Conduct](./CODE_OF_CONDUCT.md). + +## Ways to contribute + +- **Report a bug** — open a [bug report](https://github.com/SahinurDEV/ForgeData/issues/new?template=bug_report.yml). +- **Suggest a feature** — open a [feature request](https://github.com/SahinurDEV/ForgeData/issues/new?template=feature_request.yml). +- **Ask a question or share an idea** — use [GitHub Discussions](https://github.com/SahinurDEV/ForgeData/discussions). +- **Pick up an issue** — issues labelled + [`good first issue`](https://github.com/SahinurDEV/ForgeData/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) + or [`help wanted`](https://github.com/SahinurDEV/ForgeData/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) + are a great place to start. Leave a comment so others know you are working on it. +- **Report a security vulnerability** — please do **not** open a public issue; see + [SECURITY.md](./SECURITY.md). + +For larger changes (a new module, a new subpath export, a breaking API change), please open an +issue or discussion first so we can agree on the design before you invest time in it. + +## Development setup + +Requirements: **Node.js 18 or newer** (CI tests on 18, 20, 22 and 24) and npm. + +```bash +# 1. Fork the repository on GitHub, then clone your fork +git clone https://github.com//ForgeData.git +cd ForgeData + +# 2. Install dependencies (uses the committed package-lock.json) +npm ci + +# 3. Create a branch for your change +git checkout -b feat/my-change +``` + +## Project layout + +| Path | What lives there | +| --------------- | ---------------------------------------------------------------------------- | +| `src//` | One folder per generator module (`person`, `internet`, `finance`, …) | +| `src/locales/` | Built-in locale data (`en`, `bn`, `hi`, `ar`, `ja`, `fr`, `de`, `es`, `zh`) | +| `src/helpers/` | Seedable PRNG, randomness helpers, unique-value tracking, formatting | +| `src/react/` | `forgedatajs/react` subpath (provider + hooks) | +| `src/zod/` | `forgedatajs/zod` subpath (`fromZodSchema`) | +| `src/cli*.ts` | The `forgedata` CLI (`cli-core.ts` holds the testable logic) | +| `tests/` | Vitest test suites, mirroring the `src/` structure | +| `docs/` | Static website + documentation (HTML + Tailwind), deployed with GitHub Pages | +| `examples/` | Runnable Node, browser, React and CLI samples | +| `scripts/` | Build, benchmark, size-report and release helper scripts | + +## Useful scripts + +| Command | What it does | +| ----------------------- | -------------------------------------------------------------------- | +| `npm run build` | Build ESM + CJS + type declarations into `dist/` with tsup | +| `npm run dev` | Rebuild on change | +| `npm test` | Run the test suite once | +| `npm run test:watch` | Run tests in watch mode | +| `npm run test:coverage` | Run tests and enforce the 100% coverage thresholds | +| `npm run typecheck` | Type-check with `tsc --noEmit` | +| `npm run lint` | Lint with ESLint (`npm run lint:fix` to auto-fix) | +| `npm run format` | Format `src/` and `tests/` with Prettier | +| `npm run format:check` | Check formatting without writing | +| `npm run cli -- ` | Run the CLI from source, e.g. `npm run cli -- generate person.email` | +| `npm run bench` | Micro-benchmark (compares against Faker.js if it is installed) | +| `npm run size` | Build and report bundle sizes | +| `npm run preflight` | Lint + typecheck + coverage tests + build — run this before a PR | + +## Tests and coverage + +ForgeData enforces **100% statement, branch, function and line coverage** (see +[`vitest.config.ts`](./vitest.config.ts)), and CI fails if coverage drops. + +- Every new generator, option or code path needs tests in the matching file under `tests/`. +- Prefer seeded instances (`new ForgeData({ seed: 1 })`) so tests are deterministic. +- Assert on the _shape_ of generated values (format, range, membership in a locale pool) rather than + on one hard-coded random output, unless you are explicitly testing seed determinism. +- Keep the main entry point free of runtime dependencies and Node-only APIs: `src/` must run + unmodified in Node.js 18+, Bun, Deno and browsers. `react` and `zod` are optional peer + dependencies and may only be imported from their own subpaths. + +## Code style + +- TypeScript, formatted with [Prettier](https://prettier.io/) (config in `.prettierrc.json`) and + linted with ESLint. Run `npm run format` and `npm run lint` before committing. +- Public APIs should have precise return types and a short JSDoc comment. +- An [`.editorconfig`](./.editorconfig) is provided for consistent whitespace across editors. + +## Commit messages (important: they drive releases) + +This project uses [Conventional Commits](https://www.conventionalcommits.org/) and +[semantic-release](https://semantic-release.gitbook.io/). Every push to `main` is analysed and, +depending on the commit types, a new version is **automatically published to npm** with a generated +changelog entry. Pull requests are squash-merged and the **PR title becomes the commit message**, so +please give your PR a Conventional Commit title. + +| Type | Example | Release | +| ------------------------------------------------------------------ | ------------------------------------------ | ---------- | +| `feat:` | `feat(locale): add Portuguese (pt) locale` | minor | +| `fix:` | `fix(date): respect min/max in between()` | patch | +| `perf:` | `perf(prng): avoid allocation in nextInt` | patch | +| `feat!:` / `BREAKING CHANGE:` footer | `feat!: drop Node 18 support` | major | +| `docs:`, `chore:`, `test:`, `refactor:`, `style:`, `ci:`, `build:` | `docs: clarify seeding in README` | no release | + +Use an optional scope for the affected module (`person`, `internet`, `zod`, `react`, `cli`, +`locale`, …). Breaking changes must be clearly called out in the PR description. + +## Pull request process + +1. Make sure there is an issue or discussion for anything non-trivial. +2. Keep pull requests focused — one logical change per PR. +3. Run `npm run preflight` (and `npm run format:check`) locally; all checks must pass. +4. Update documentation when behaviour changes: `README.md` and, where relevant, the docs site in + `docs/docs.html`. Do not edit `CHANGELOG.md` — semantic-release maintains it. +5. Open the PR against `main` with a Conventional Commit title and fill in the PR template. +6. CI (lint, typecheck, 100%-coverage tests and build on Node 18/20/22/24) must be green. +7. A maintainer ([@SahinurDEV](https://github.com/SahinurDEV)) will review. Please be patient and + responsive to feedback; once approved the PR is squash-merged and, if it contains a `feat`/`fix`, + released to npm automatically. + +## Adding a new locale + +1. Create `src/locales/.ts` exporting a `LocaleData` object (see `src/locales/types.ts` and an + existing locale such as `src/locales/de.ts` for the shape). +2. Register it in `src/locales/index.ts` (import, re-export and add it to `builtInLocales`). +3. Add tests (e.g. in `tests/locales/`) and keep coverage at 100%. +4. Update the locale lists in `README.md` and `docs/docs.html`. + +Use realistic, commonly used names and places, and avoid offensive or real-person-identifying data. + +## Adding a new generator + +1. Add the method to the relevant module class in `src//index.ts` (it is picked up by + `forge.listGenerators()` and the CLI automatically via introspection). +2. Use the instance's seeded randomness helpers — never `Math.random()` directly — so output stays + deterministic for a given seed. +3. Add tests and document it in the README's module table and the docs site. + +## License + +By contributing, you agree that your contributions will be licensed under the project's +[MIT License](./LICENSE). diff --git a/LICENSE b/LICENSE index f6f1663..caa5068 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2026 ForgeData Contributors +Copyright (c) 2026 Sahinur Islam and ForgeData contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index d06b31e..33c56fb 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,9 @@ A production-ready alternative to Faker.js — with React integration and a CLI [![bundle size](https://img.shields.io/bundlephobia/minzip/forgedatajs.svg)](https://bundlephobia.com/package/forgedatajs) [![types](https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white)](./src/index.ts) [![license](https://img.shields.io/npm/l/forgedatajs.svg?color=6366f1)](./LICENSE) +[![contributors](https://img.shields.io/github/contributors/SahinurDEV/ForgeData?color=6366f1)](https://github.com/SahinurDEV/ForgeData/graphs/contributors) +[![good first issues](https://img.shields.io/github/issues/SahinurDEV/ForgeData/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/SahinurDEV/ForgeData/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) [**Website**](https://sahinurdev.github.io/ForgeData/)  ·  [**Try it live**](https://sahinurdev.github.io/ForgeData/#playground)  ·  @@ -56,6 +59,7 @@ A production-ready alternative to Faker.js — with React integration and a CLI - [Development](#development) - [Website](#website) - [Publishing](#publishing) +- [Contributing](#contributing) - [License](#license) ## Install @@ -71,12 +75,12 @@ import { ForgeData } from "forgedatajs"; const forge = new ForgeData(); -forge.person.fullName(); // "Ava Thompson" -forge.internet.email(); // "ava.thompson@example.com" -forge.location.country(); // "Canada" +forge.person.fullName(); // "Ava Thompson" +forge.internet.email(); // "ava.thompson@example.com" +forge.location.country(); // "Canada" forge.finance.creditCardNumber(); // "4539123456781234" -forge.phone.number(); // "+1-555-123-4567" -forge.ai.prompt(); // "Explain quantum computing to a beginner..." +forge.phone.number(); // "+1-555-123-4567" +forge.ai.prompt(); // "Explain quantum computing to a beginner..." ``` Or use the ready-made default instance for quick scripts: @@ -93,7 +97,7 @@ console.log(forge.person.fullName()); const forge = new ForgeData({ seed: 42 }); forge.person.fullName(); // always the same value for seed 42 -forge.seed(42); // reseed an existing instance +forge.seed(42); // reseed an existing instance ``` Seeds accept a `number` or a `string` (strings are hashed into a seed), so you can seed with something readable like a test name. @@ -104,8 +108,8 @@ Seeds accept a `number` or a `string` (strings are hashed into a seed), so you c const forge = new ForgeData({ locale: "ja" }); forge.person.fullName(); // Japanese name pool -forge.locale("fr"); // switch at runtime -forge.locale(); // "fr" — read the current locale +forge.locale("fr"); // switch at runtime +forge.locale(); // "fr" — read the current locale ``` Built-in locales: `en`, `bn` (Bangla), `hi` (Hindi), `ar` (Arabic), `ja` (Japanese), `fr` (French), `de` (German), `es` (Spanish), `zh` (Chinese). @@ -142,7 +146,7 @@ forge.custom.pokemon(); // "Pikachu" ## Unique values ```ts -forge.unique.email(); // never repeats for this ForgeData instance +forge.unique.email(); // never repeats for this ForgeData instance forge.unique.username(); forge.unique.uuid(); @@ -230,7 +234,11 @@ function UserCard() { (forge) => ({ name: forge.person.fullName(), email: forge.internet.email() }), [], ); - return
{user.name} — {user.email}
; + return ( +
+ {user.name} — {user.email} +
+ ); } ``` @@ -250,24 +258,24 @@ Install it globally (`npm install -g forgedatajs`) to just run `forgedata ...` d ## Modules -| Module | Examples | -|-------------|----------| -| `person` | `firstName()`, `lastName()`, `fullName()`, `gender()`, `jobTitle()`, `profession()` | -| `internet` | `email()`, `username()`, `password()`, `url()`, `domain()`, `ipv4()`, `ipv6()`, `mac()`, `userAgent()`, `jwt()`, `apiKey()`, `jwtSecret()` | -| `company` | `name()`, `catchPhrase()`, `logo()` | -| `finance` | `currency()`, `amount()`, `creditCardNumber()`, `creditCardCVV()`, `iban()`, `bitcoinAddress()`, `ethereumAddress()`, `cryptoCoin()`, `stockSymbol()` | -| `location` | `country()`, `state()`, `city()`, `zipCode()`, `latitude()`, `longitude()`, `timezone()`, `airport()` | -| `commerce` | `productName()`, `price()`, `department()`, `isbn()`, `barcode()` | -| `phone` | `number()`, `imei()` | -| `date` | `past()`, `future()`, `recent()`, `birthdate()`, `month()`, `weekday()`, `between()` | -| `image` | `avatar()`, `url()`, `category()`, `dataUri()` | -| `lorem` | `word()`, `words()`, `sentence()`, `paragraph()`, `slug()`, `markdown()`, `html()` | -| `color` | `hex()`, `rgb()`, `rgba()`, `hsl()`, `cssColorName()`, `tailwindColor()`, `materialColor()`, `svgPattern()` | -| `vehicle` | `manufacturer()`, `model()`, `type()`, `vin()` | -| `animal` | `type()`, `name()` | -| `science` | `unit()`, `chemicalElement()` | -| `ai` | `prompt()`, `chatConversation()`, `codeSnippet()`, `sqlQuery()`, `json()`, `markdown()`, `apiResponse()`, `logLine()`, `commitMessage()`, `issueTitle()`, `prDescription()` | -| `misc` | `emoji()`, `hashtag()`, `programmingLanguage()`, `githubUsername()`, `gitCommitHash()`, `semver()`, `dockerImageName()`, `npmPackageName()`, `otp()`, `licenseKey()`, `qrData()`, `movie()`, `book()`, `music()`, `food()`, `holiday()`, `university()` | +| Module | Examples | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `person` | `firstName()`, `lastName()`, `fullName()`, `gender()`, `jobTitle()`, `profession()` | +| `internet` | `email()`, `username()`, `password()`, `url()`, `domain()`, `ipv4()`, `ipv6()`, `mac()`, `userAgent()`, `jwt()`, `apiKey()`, `jwtSecret()` | +| `company` | `name()`, `catchPhrase()`, `logo()` | +| `finance` | `currency()`, `amount()`, `creditCardNumber()`, `creditCardCVV()`, `iban()`, `bitcoinAddress()`, `ethereumAddress()`, `cryptoCoin()`, `stockSymbol()` | +| `location` | `country()`, `state()`, `city()`, `zipCode()`, `latitude()`, `longitude()`, `timezone()`, `airport()` | +| `commerce` | `productName()`, `price()`, `department()`, `isbn()`, `barcode()` | +| `phone` | `number()`, `imei()` | +| `date` | `past()`, `future()`, `recent()`, `birthdate()`, `month()`, `weekday()`, `between()` | +| `image` | `avatar()`, `url()`, `category()`, `dataUri()` | +| `lorem` | `word()`, `words()`, `sentence()`, `paragraph()`, `slug()`, `markdown()`, `html()` | +| `color` | `hex()`, `rgb()`, `rgba()`, `hsl()`, `cssColorName()`, `tailwindColor()`, `materialColor()`, `svgPattern()` | +| `vehicle` | `manufacturer()`, `model()`, `type()`, `vin()` | +| `animal` | `type()`, `name()` | +| `science` | `unit()`, `chemicalElement()` | +| `ai` | `prompt()`, `chatConversation()`, `codeSnippet()`, `sqlQuery()`, `json()`, `markdown()`, `apiResponse()`, `logLine()`, `commitMessage()`, `issueTitle()`, `prDescription()` | +| `misc` | `emoji()`, `hashtag()`, `programmingLanguage()`, `githubUsername()`, `gitCommitHash()`, `semver()`, `dockerImageName()`, `npmPackageName()`, `otp()`, `licenseKey()`, `qrData()`, `movie()`, `book()`, `music()`, `food()`, `holiday()`, `university()` | Run `forge.listGenerators().length` to see the exact live count (100+). @@ -291,7 +299,7 @@ npm run bench # micro-benchmark, compares against faker if installed npm run cli -- list # run the CLI from source during development ``` -See the [documentation site](https://sahinurdev.github.io/ForgeData/docs.html) (built from `docs/docs.html`) for the getting-started guide, full API reference, React guide, CLI reference, migration guide from Faker.js, and contributing guide. See [examples/](./examples) for runnable Node, browser, React, and CLI samples. +See the [documentation site](https://sahinurdev.github.io/ForgeData/docs.html) (built from `docs/docs.html`) for the getting-started guide, full API reference, React guide, CLI reference, migration guide from Faker.js, and contributing guide. See [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. See [examples/](./examples) for runnable Node, browser, React, and CLI samples. ## Website @@ -308,18 +316,29 @@ Deployed straight from the repo — no CI needed: **Settings → Pages → Sourc ## Publishing -This repo is fully set up to publish, but nothing publishes itself: +Releases are fully automated. On every push to `main`, `.github/workflows/release.yml` runs [semantic-release](https://semantic-release.gitbook.io/): it derives the next version from [Conventional Commits](https://www.conventionalcommits.org/) (`feat:` → minor, `fix:`/`perf:` → patch, `BREAKING CHANGE` → major; `docs:`/`chore:`/`test:` etc. don't release), updates `CHANGELOG.md`, tags, creates a GitHub release and publishes `forgedatajs` to npm via [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC, with provenance) — no `NPM_TOKEN` secret is needed. It relies on a one-time trusted publisher for `forgedatajs` on npmjs.com (GitHub Actions, `SahinurDEV` / `ForgeData`, workflow `release.yml`). + +To check what the next release would be locally: ```bash -npm run preflight # lint + typecheck + 100%-coverage tests + build -npm login -npm publish --access public +npm run preflight # lint + typecheck + 100%-coverage tests + build +npm run release:dry-run # semantic-release --dry-run --no-ci ``` -`scripts/publish.sh` wraps that sequence with a confirmation prompt, and `RELEASE_NOTES.md` has a ready-to-paste description for the GitHub Release / npm announcement. +A manual fallback (`npm login && npm publish --access public`, wrapped with a confirmation prompt in `scripts/publish.sh`) is still available for maintainers. + +## Contributing + +Contributions of all sizes are welcome — new generators, locales, bug fixes, docs and tooling. + +- Read the [contributing guide](./CONTRIBUTING.md) for setup, scripts, test/coverage expectations and the PR process. +- Looking for somewhere to start? Check the [good first issues](https://github.com/SahinurDEV/ForgeData/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and [help wanted](https://github.com/SahinurDEV/ForgeData/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) issues. +- Questions and ideas go to [GitHub Discussions](https://github.com/SahinurDEV/ForgeData/discussions); bugs and feature requests to [issues](https://github.com/SahinurDEV/ForgeData/issues/new/choose). +- Commit messages / PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) because they drive automated releases. +- Please follow the [Code of Conduct](./CODE_OF_CONDUCT.md), and report security issues privately as described in [SECURITY.md](./SECURITY.md). -For every release after the first, `.github/workflows/release.yml` runs [semantic-release](https://semantic-release.gitbook.io/) on pushes to `main` — it derives the next version from [Conventional Commits](https://www.conventionalcommits.org/), updates `CHANGELOG.md`, tags, and publishes to npm via [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC, with provenance) — no `NPM_TOKEN` secret is needed. It requires a one-time trusted publisher for `forgedatajs` on npmjs.com (GitHub Actions, `SahinurDEV` / `ForgeData`, workflow `release.yml`); see the docs site's [Contributing](https://sahinurdev.github.io/ForgeData/docs.html#contributing) section. +Thanks to [everyone who has contributed](https://github.com/SahinurDEV/ForgeData/graphs/contributors)! ## License -MIT +[MIT](./LICENSE) © 2026 Sahinur Islam and ForgeData contributors diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..6cf3f98 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,42 @@ +# Security Policy + +## Supported versions + +ForgeData is released continuously from `main` with semantic-release. Security fixes are made in the +latest published version of [`forgedatajs`](https://www.npmjs.com/package/forgedatajs) only. + +| Version | Supported | +| -------------- | ------------------ | +| Latest `0.x` | :white_check_mark: | +| Older releases | :x: | + +Please upgrade to the latest version before reporting an issue. + +## Reporting a vulnerability + +**Please do not report security vulnerabilities through public GitHub issues, discussions or pull +requests.** + +Report them privately using GitHub's private vulnerability reporting: + +1. Go to the [Security tab](https://github.com/SahinurDEV/ForgeData/security) of this repository. +2. Click **Report a vulnerability** + ([direct link](https://github.com/SahinurDEV/ForgeData/security/advisories/new)). +3. Describe the issue, including the affected version, steps to reproduce or a proof of concept, and + the potential impact. + +The report is visible only to the maintainer. You can expect an initial response acknowledging the +report as soon as possible; we will keep you informed about the investigation and fix, coordinate a +disclosure date with you, and credit you in the published advisory unless you prefer to remain +anonymous. + +## Scope + +ForgeData generates **fake** data for testing, prototyping and demos. Values such as credit card +numbers, IBANs, API keys, JWTs, passwords and OTPs are random and are **not** cryptographically +secure. Do not use ForgeData to generate real secrets, credentials or security tokens — that is +working as intended and not a vulnerability. + +Relevant reports include, for example: code execution or prototype pollution via the library or the +`forgedata` CLI, denial of service caused by crafted input (e.g. Zod schemas or CLI flags), or a +compromised build/release pipeline or published package.