Merge branch 'main' into rename-module-classes

docs/.vitepress/components/api-docs/method.ts

@@ -6,6 +6,7 @@ export interface Method {
   readonly returns: string;
   readonly examples: string; // HTML
   readonly deprecated: boolean;
+  readonly since: string;
   readonly seeAlsos: string[];
 }
 

docs/.vitepress/components/api-docs/method.vue

@@ -19,6 +19,12 @@ function seeAlsoToUrl(see: string): string {
 
     <div v-html="props.method.description"></div>
 
+    <div v-if="props.method.since">
+      <p>
+        <em>Available since v<span v-html="props.method.since" /></em>
+      </p>
+    </div>
+
     <MethodParameters
       v-if="props.method.parameters.length > 0"
       :parameters="props.method.parameters"

docs/.vitepress/config.ts

@@ -164,9 +164,22 @@ export default defineConfig({
               text: 'Announcements',
               link: '/about/announcements',
               items: [
+                { text: '2022-09-08', link: '/about/announcements/2022-09-08' },
                 { text: '2022-01-14', link: '/about/announcements/2022-01-14' },
               ],
             },
+            {
+              text: 'Roadmap',
+              link: '/about/roadmap/',
+              items: [
+                { text: 'v8 - Make Faker Handier', link: '/about/roadmap/v8' },
+                {
+                  text: 'v7 - Cleanup & Improvements',
+                  link: '/about/roadmap/v7',
+                },
+                { text: 'v6 - Continue Faker', link: '/about/roadmap/v6' },
+              ],
+            },
             {
               text: 'Team',
               link: '/about/team',

docs/about/announcements.md

@@ -4,4 +4,5 @@ editLink: false
 
 # Announcements
 
+- [2022-09-08 - New Roadmap Published](./announcements/2022-09-08)
 - [2022-01-14 - An update from the Faker team](./announcements/2022-01-14)

docs/about/announcements/2022-01-14.md

@@ -10,8 +10,6 @@ _January 14th, 2022_
 
 We want the project to have a fresh start and become _even cooler_.
 
-[[toc]]
-
 ## What is Faker?
 
 Faker is a library that generates fake (but reasonable) data for you. Mock data. Data for testing, development, and the like.

docs/about/announcements/2022-09-08.md

@@ -0,0 +1,26 @@
+---
+editLink: false
+---
+
+# New Roadmap Published
+
+We haven't made any announcements for a long time, but we are happy to announce that we just published the new roadmap for v8.
+
+Our main focus for v8 is to make Faker more lightweight and flexible.
+A huge part of that is better tree shaking support.
+
+Currently, if you just want to generate some reproducible numbers, then you need the entire Faker package.
+First, you have to download almost 10MB of data (mostly locales; duplicated for ESM and CJS) and ship half of that (one of them).
+
+We wont tackle the download size for now,
+but we hope to reduce the shipped size significantly (deduplicate locale data) on our side and allow your build process to discard more unused methods and data.
+This should also improve js startup/parse times.
+
+If we are successful, you will only need a few KB of code for numbers and only the locales you need for more complex things such as names.
+With a bit of setup on your side, you can ship only the parts of the locale data you actually need.
+So no more finance data and mime-types, just for a first name.
+
+For more details refer to our roadmap:
+
+- [Roadmap - Overview](../roadmap/index.html)
+- [Roadmap v8 - Make Faker Handier](../roadmap/v8.html)

docs/about/roadmap/index.md

@@ -0,0 +1,17 @@
+---
+editLink: false
+---
+
+# Roadmap
+
+These pages outline our roadmap for past and future versions.
+Click on the specific versions for more details.
+
+## Upcoming Versions
+
+- [v8 - Make Faker Handier](v8.html)
+
+## Previous Versions
+
+- [v7 - Cleanup & Improvements](v7.html)
+- [v6 - Continue Faker](v6.html)

docs/about/roadmap/v6.md

@@ -0,0 +1,70 @@
+---
+editLink: false
+---
+
+# v6 - Continue Faker
+
+The main task of v6 is fixing technical debts and some cleanup.
+
+## v6.0 - Ensure project foundation
+
+- Rewrite project in TypeScript
+- Update dependencies and automate the process
+- Add/Extend build pipeline
+- Write JSDocs for most of the modules and methods
+- Add online documentation/website
+
+[v6.0 Tasks](https://github.com/faker-js/faker/milestone/1)
+
+**Releases**
+
+- [v6.0.0-alpha.0](https://github.com/faker-js/faker/releases/tag/v6.0.0-alpha.0)
+- [v6.0.0-alpha.2](https://github.com/faker-js/faker/releases/tag/v6.0.0-alpha.2)
+- [v6.0.0-alpha.3](https://github.com/faker-js/faker/releases/tag/v6.0.0-alpha.3)
+- [v6.0.0-alpha.4](https://github.com/faker-js/faker/releases/tag/v6.0.0-alpha.4)
+- [v6.0.0-alpha.5](https://github.com/faker-js/faker/releases/tag/v6.0.0-alpha.5)
+- [v6.0.0-alpha.6](https://github.com/faker-js/faker/releases/tag/v6.0.0-alpha.6)
+- [v6.0.0-alpha.7](https://github.com/faker-js/faker/releases/tag/v6.0.0-alpha.7)
+- [v6.0.0-beta.0](https://github.com/faker-js/faker/releases/tag/v6.0.0-beta.0)
+- [v6.0.0](https://github.com/faker-js/faker/releases/tag/v6.0.0)
+
+## v6.1 - First Bugfixes
+
+- Fix bugs in the implementation and data
+- Standardize some method parameters
+- Deprecate duplicate methods
+- Extend unit tests
+- Link missing locales
+- Improve documentation
+
+[v6.1 Tasks](https://github.com/faker-js/faker/milestone/2)
+
+**Releases**
+
+- [v6.1.0](https://github.com/faker-js/faker/releases/tag/v6.1.0)
+- [v6.1.1](https://github.com/faker-js/faker/releases/tag/v6.1.1)
+- [v6.1.2](https://github.com/faker-js/faker/releases/tag/v6.1.2)
+
+## v6.2 - First New Features
+
+- Introduce the first new features
+- Add/Update some locales
+- More cleanup
+
+[v6.2 Tasks](https://github.com/faker-js/faker/milestone/5)
+
+**Releases**
+
+- [v6.2.0](https://github.com/faker-js/faker/releases/tag/v6.2.0)
+
+## v6.x
+
+Further improvements
+
+- [v6.3 Tasks](https://github.com/faker-js/faker/milestone/7)
+- [v6.x Tasks](https://github.com/faker-js/faker/milestone/3)
+
+**Releases**
+
+- [v6.3.0](https://github.com/faker-js/faker/releases/tag/v6.3.0)
+- [v6.3.1](https://github.com/faker-js/faker/releases/tag/v6.3.1)

docs/about/roadmap/v7.md

@@ -0,0 +1,38 @@
+---
+editLink: false
+---
+
+# v7 - Cleanup & Improvements
+
+In v7 we will remove some methods that we have deprecated in v6 and restructure the sources a bit.
+It will be the first release with small breaking changes since we maintain it.
+
+## v7.0 - Structurally Breaking Changes
+
+- Remove deprecations
+- Remove faker default export
+- Target es2020
+- Drop Node v12 support
+- Reorganize source folder
+- More features
+
+[v7.0 Tasks](https://github.com/faker-js/faker/milestone/8)
+
+**Releases**
+
+- [v7.0.0](https://github.com/faker-js/faker/releases/tag/v7.0.0)
+- [v7.0.1](https://github.com/faker-js/faker/releases/tag/v7.0.1)
+
+## v7.x
+
+Further improvements
+
+- [v7.x Tasks](https://github.com/faker-js/faker/milestone/4)
+
+**Releases**
+
+- [v7.1.0](https://github.com/faker-js/faker/releases/tag/v7.1.0)
+- [v7.2.0](https://github.com/faker-js/faker/releases/tag/v7.2.0)
+- [v7.3.0](https://github.com/faker-js/faker/releases/tag/v7.3.0)
+- [v7.4.0](https://github.com/faker-js/faker/releases/tag/v7.4.0)
+- [v7.5.0](https://github.com/faker-js/faker/releases/tag/v7.5.0)

docs/about/roadmap/v8.md

@@ -0,0 +1,35 @@
+---
+editLink: false
+---
+
+# v8 - Make Faker Handier
+
+Our main goal in v8 is to make Faker more lightweight and more flexible.
+
+## v8.0 - Module Re-Shuffling
+
+Finish the module shuffling.
+
+- Remove locale switching support
+- Move String and Number methods into own modules
+- Rename Name module to Person
+- Rename Address module to Location
+- Check modules and methods regarding their name and location
+- Try to eliminate circular dependencies in modules
+- Standardize function parameters and defaults
+- Rewrite image module / providers
+
+[v8.0 Tasks](https://github.com/faker-js/faker/milestone/10)
+
+## v8.1 - Split Faker Class
+
+Split the Faker class into smaller units so you don't have ship an entire locale if you only generate some strings and numbers.
+
+[v8.1 Tasks](https://github.com/faker-js/faker/milestone/11)
+
+## v8.x - Tree-Shakeable Module-Functions
+
+Refactor modules to be tree shakeable.
+Potentially allowing individual Faker methods to be called by themselves.
+
+[v8.x Tasks](https://github.com/faker-js/faker/milestone/12)

docs/guide/migration-guide-v5.md

@@ -1,8 +1,6 @@
 # Migrating from Faker v5 to v6
 
-[[toc]]
-
-### ESM Support
+## ESM Support
 
 **New Format**: We're now ESM compatible! We've dropped the Browser bundle in favor of ESM.
 
@@ -16,7 +14,7 @@ So if you'd like to use `Faker` in the **browser**, simply include it using a [J
 </script>
 ```
 
-### Remove all references to `faker` from your project. The new package is located at `@faker-js/faker`
+## Remove all references to `faker` from your project. The new package is located at `@faker-js/faker`
 
 :::warning
 You **MUST** swap all references from the `faker` package to the new `@faker-js/faker` package.
@@ -28,13 +26,13 @@ If you depend on a specific version of Faker you still can reference the version
 `npm i @faker-js/faker@5.5.3 -D` will work just fine 😄.
 :::
 
-### TypeScript
+## TypeScript
 
 :::tip TypeScript Improvements
 Faker now ships with its own types! Remove `@types/faker` from your `package.json` to avoid conflicts.
 :::
 
-### Tree-shaking
+## Tree-shaking
 
 :::warning
 Tree shaking is not yet fully supported due to some structural issues. But we plan to make Faker fully tree-shakable in the future.

docs/guide/migration-guide-v6.md

@@ -1,12 +1,10 @@
 # Migrating from Faker v6 to v7
 
-[[toc]]
-
-### Node 12 no longer supported
+## Node 12 no longer supported
 
 You need at least Node 14 to use Faker.
 
-### Default export removed
+## Default export removed
 
 If you were previously importing faker like this:
 
@@ -20,7 +18,7 @@ You must instead use:
 import { faker } from '@faker-js/faker';
 ```
 
-### Deprecated methods changed
+## Deprecated methods changed
 
 Several methods were renamed or moved:
 
@@ -39,7 +37,7 @@ Several methods were renamed or moved:
 | faker.datatype.hexaDecimal | faker.datatype.hexadecimal                             |
 | faker.name.title           | faker.name.jobTitle                                    |
 
-### Deprecated methods removed
+## Deprecated methods removed
 
 Some methods were removed without a direct alternative. If you are using any of these methods you should build an object containing the specific properties you need.
 

scripts/apidoc/signature.ts

@@ -21,6 +21,7 @@ import { faker } from '../../src';
 import {
   extractRawExamples,
   extractSeeAlsos,
+  extractSince,
   formatTypescript,
   isDeprecated,
   joinTagParts,
@@ -153,6 +154,7 @@ export function analyzeSignature(
     title: prettyMethodName,
     description: mdToHtml(toBlock(signature.comment)),
     parameters: parameters,
+    since: extractSince(signature),
     returns: typeToText(signature.type),
     examples: mdToHtml(`${code}ts\n${examples}${code}`),
     deprecated: isDeprecated(signature),

scripts/apidoc/utils.ts

@@ -146,3 +146,14 @@ export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined {
 export function isDeprecated(signature: SignatureReflection): boolean {
   return extractTagContent('@deprecated', signature).length > 0;
 }
+
+/**
+ * Extracts the "since" tag from the provided signature.
+ *
+ * @param signature The signature to check.
+ *
+ * @returns the contents of the @since tag
+ */
+export function extractSince(signature: SignatureReflection): string {
+  return extractTagContent('@since', signature).join().trim();
+}