Merge branch 'next' into refactor/location/rename-city-definition-to-…

…city-patterns

.eslintrc.js

@@ -12,6 +12,7 @@ module.exports = defineConfig({
     browser: true,
     node: true,
   },
+  reportUnusedDisableDirectives: true,
   extends: [
     'eslint:recommended',
     'plugin:@typescript-eslint/recommended',

CONTRIBUTING.md

@@ -4,7 +4,20 @@ If you want to make `Faker` a better, please read the following contribution gui
 
 # Important
 
-Please make sure that you run `pnpm run preflight` before making a PR to ensure that everything is working from the start.
+Please make sure that you run `pnpm run preflight` before making a PR to ensure that everything is working from the start.  
+This is a shorthand for running the following scripts in order:
+
+- `pnpm install` - installs npm packages defined in package.json
+- `pnpm run generate:locales` - generates locale files
+- `pnpm run generate:api-doc` - generates API documentation
+- `pnpm run format` - runs [prettify](https://github.com/prettier/prettier) to format code
+- `pnpm run lint` - runs [ESLint](https://github.com/eslint/eslint) to enforce project code standards
+- `pnpm run build:clean` - removes artifacts from previous builds
+- `pnpm run build:code` - builds the code, both CommonJS and ESM versions
+- `pnpm run build:types` - builds the TypeScript type definitions
+- `pnpm run test:update-snapshots ` - runs all tests, and updates any snapshots if needed
+- `pnpm run ts-check:scripts` - checks that there are no TypeScript errors in script files
+- `pnpm run ts-check:tests` - checks that there are no TypeScript errors in test or script files
 
 ## Good to know
 

docs/guide/localization.md

@@ -91,6 +91,7 @@ In this example there are 5 locales. Each of these is checked in order, and the
 | `en_CA`       | English (Canada)          | `fakerEN_CA`       |
 | `en_GB`       | English (Great Britain)   | `fakerEN_GB`       |
 | `en_GH`       | English (Ghana)           | `fakerEN_GH`       |
+| `en_HK`       | English (Hong Kong)       | `fakerEN_HK`       |
 | `en_IE`       | English (Ireland)         | `fakerEN_IE`       |
 | `en_IN`       | English (India)           | `fakerEN_IN`       |
 | `en_NG`       | English (Nigeria)         | `fakerEN_NG`       |

docs/guide/upgrading.md

@@ -123,20 +123,12 @@ fakerES.music.songName(); // 'I Want to Hold Your Hand' (fallback from en)
 fakerES_noFallbacks.music.songName(); // throws a FakerError
 ```
 
-This also has an impact on data that aren't applicable to a locale, for example Chinese doesn't use prefixes in names.
+This also has an impact on data that aren't applicable to a locale, for example Hong Kong (`en_HK`) doesn't use ZIP codes/postcodes.
 
 ```ts
-import { faker, fakerZH_CN, zh_CN } from '@faker-js/faker';
-
-const fakerZH_CN_noFallbacks = new Faker({
-  locale: [zh_CN],
-});
-
-faker.name.prefix(); // 'Mr'
-// Previously:
-//fakerZH_CN_noFallbacks.person.prefix(); // undefined
-// Now:
-fakerZH_CN.person.prefix(); // throws a FakerError
+import { fakerEN_US, fakerEN_HK } from '@faker-js/faker';
+fakerEN_US.location.zipCode(); // 90210
+fakerEN_HK.location.zipCode(); // throws a FakerError
 ```
 
 ### `faker.mersenne` and `faker.helpers.repeatString` removed
@@ -316,9 +308,9 @@ faker.number.float({ max: 100, precision: 0.01 }); // 35.21
 The method `faker.datatype.array` has been deprecated and will be removed in v9.
 If you need an array of useful values, you are better off creating your own one using `faker.helpers.multiple`.
 
-### `faker.datatype.datetime` deprecated in favor of `faker.date.between`
+### `faker.datatype.datetime` deprecated in favor of `faker.date.between` and `faker.date.anytime`
 
-The `datetime` method previously found in `faker.datatype` has been deprecated, use `faker.date.between` instead.
+The `datetime` method previously found in `faker.datatype` has been deprecated, use `faker.date.between` or `faker.date.anytime` instead.
 
 ### `allowLeadingZeros` behavior change in `faker.string.numeric`
 

package.json

@@ -76,7 +76,7 @@
     "docs:serve": "vitepress serve docs --port 5173",
     "docs:diff": "tsx ./scripts/diff.ts",
     "format": "prettier --cache --write .",
-    "lint": "eslint --cache --cache-strategy content .",
+    "lint": "eslint --cache --cache-strategy content --report-unused-disable-directives .",
     "ts-check": "run-s ts-check:scripts ts-check:tests",
     "ts-check:scripts": "tsc --project tsconfig.check-scripts.json",
     "ts-check:tests": "tsc --project tsconfig.check-tests.json",

src/internal/deprecated.ts

@@ -1,4 +1,3 @@
-/* eslint-disable jsdoc/check-tag-names */
 /* eslint-disable jsdoc/require-param */
 
 /**

src/locale-proxy.ts

@@ -31,6 +31,10 @@ export function createLocaleProxy(locale: LocaleDefinition): LocaleProxy {
       target: LocaleDefinition,
       categoryName: keyof LocaleDefinition
     ): LocaleDefinition[keyof LocaleDefinition] {
+      if (typeof categoryName === 'symbol' || categoryName === 'nodeType') {
+        return target[categoryName];
+      }
+
       if (categoryName in proxies) {
         return proxies[categoryName];
       }
@@ -69,7 +73,9 @@ function createCategoryProxy<
       entryName: keyof CategoryData
     ): CategoryData[keyof CategoryData] {
       const value = target[entryName];
-      if (value === null) {
+      if (typeof entryName === 'symbol' || entryName === 'nodeType') {
+        return value;
+      } else if (value === null) {
         throw new FakerError(
           `The locale data for '${categoryName}.${entryName.toString()}' aren't applicable to this locale.
   If you think this is a bug, please report it at: https://github.com/faker-js/faker`

src/locale/en_HK.ts

@@ -0,0 +1,13 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+
+import { Faker } from '../faker';
+import base from '../locales/base';
+import en from '../locales/en';
+import en_HK from '../locales/en_HK';
+
+export const faker = new Faker({
+  locale: [en_HK, en, base],
+});

src/locale/index.ts

@@ -20,6 +20,7 @@ import { faker as fakerEN_BORK } from './en_BORK';
 import { faker as fakerEN_CA } from './en_CA';
 import { faker as fakerEN_GB } from './en_GB';
 import { faker as fakerEN_GH } from './en_GH';
+import { faker as fakerEN_HK } from './en_HK';
 import { faker as fakerEN_IE } from './en_IE';
 import { faker as fakerEN_IN } from './en_IN';
 import { faker as fakerEN_NG } from './en_NG';
@@ -84,6 +85,7 @@ export {
   fakerEN_CA,
   fakerEN_GB,
   fakerEN_GH,
+  fakerEN_HK,
   fakerEN_IE,
   fakerEN_IN,
   fakerEN_NG,
@@ -149,6 +151,7 @@ export const allFakers = {
   en_CA: fakerEN_CA,
   en_GB: fakerEN_GB,
   en_GH: fakerEN_GH,
+  en_HK: fakerEN_HK,
   en_IE: fakerEN_IE,
   en_IN: fakerEN_IN,
   en_NG: fakerEN_NG,

src/locales/en_HK/company/index.ts

@@ -0,0 +1,12 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { CompanyDefinitions } from '../../..';
+import suffix from './suffix';
+
+const company: CompanyDefinitions = {
+  suffix,
+};
+
+export default company;

src/locales/en_HK/company/suffix.ts

@@ -0,0 +1 @@
+export default ['Ltd.', 'Co. Ltd.'];

src/locales/en_HK/index.ts

@@ -0,0 +1,22 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { LocaleDefinition } from '../..';
+import company from './company';
+import internet from './internet';
+import location from './location';
+import metadata from './metadata';
+import person from './person';
+import phone_number from './phone_number';
+
+const en_HK: LocaleDefinition = {
+  company,
+  internet,
+  location,
+  metadata,
+  person,
+  phone_number,
+};
+
+export default en_HK;

src/locales/en_HK/internet/domain_suffix.ts

@@ -0,0 +1 @@
+export default ['com', 'hk', 'com.hk', 'org.hk'];

src/locales/en_HK/internet/index.ts

@@ -0,0 +1,12 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { InternetDefinitions } from '../../..';
+import domain_suffix from './domain_suffix';
+
+const internet: InternetDefinitions = {
+  domain_suffix,
+};
+
+export default internet;

src/locales/en_HK/location/building_number.ts

@@ -0,0 +1 @@
+export default ['###', '##', '#'];

src/locales/en_HK/location/city.ts

@@ -0,0 +1,106 @@
+export default [
+  'Aberdeen',
+  'Ap Lei Chau',
+  'Causeway Bay',
+  'Chai Wan',
+  'Cheung Chau',
+  'Cheung Fat',
+  'Cheung Sha Wan',
+  'Choi Hung Chuen',
+  'Choi Ming',
+  'Chuk Yuen',
+  'Cyberport',
+  'Discovery Bay',
+  'Fairview Park',
+  'Fanling',
+  'Fo Tan',
+  'Fu Shan',
+  'Fu Shin',
+  'Fu Tai',
+  'Happy Valley',
+  'Heng Fa Chuen',
+  'Heng On',
+  'Hin Keng',
+  'Ho Man Tin',
+  'Hung Hom Bay',
+  'Kam Tai',
+  'Kam Tin',
+  'Kennedy Town',
+  'Kowloon',
+  'Kowloon Bay',
+  'Kowloon Central',
+  'Kowloon City',
+  'Kowloon East',
+  'Kwai Chung',
+  'Kwai Fong',
+  'Kwai Shing',
+  'Kwong Yuen',
+  'Kwun Tong',
+  'Lai King',
+  'Lai Kok',
+  'Lam Tin',
+  'Lamma',
+  'Lee On',
+  'Lei Muk Shue',
+  'Lei Tung',
+  'Leung King',
+  'Lok Fu',
+  'Ma On Shan',
+  'Mei Foo Sun Chuen',
+  'Mei Lam',
+  'Mong Kok',
+  'Mui Wo',
+  'Ngau Chi Wan',
+  'Ngau Tau Kok',
+  'Oi Man',
+  'Peak',
+  'Peng Chau',
+  'Po Lam',
+  'Pok Fu Lam',
+  'Repulse Bay',
+  'Sai Kung',
+  'Sai Ying Pun',
+  'San Tin',
+  'Sau Mau Ping',
+  'Sha Kok',
+  'Sha Tau Kok',
+  'Sha Tin',
+  'Sham Shui Po',
+  'Shau Kei Wan',
+  'Shek Kip Mei',
+  'Shek Lei',
+  'Shek Wai Kok',
+  'Shek Wu Hui',
+  'Sheung Tak',
+  'Sheung Wan',
+  'Shun Lee',
+  'Siu Sai Wan',
+  'So Uk',
+  'Stanley',
+  'Sun Chui',
+  'Tai Hing',
+  'Tai Kok Tsui',
+  'Tai Koo Shing',
+  'Tai O',
+  'Tai Po',
+  'Tin Yiu',
+  'Tin Yuet',
+  'To Kwa Wan',
+  'Tsat Tsz Mui',
+  'Tseung Kwan O',
+  'Tsim Sha Tsui',
+  'Tsing Yi',
+  'Tsuen Wan',
+  'Tsz Wan Shan',
+  'Tuen Mun',
+  'Tung Chung',
+  'Wah Fu',
+  'Wah Ming',
+  'Wan Chai',
+  'Wan Tau Tong',
+  'Wo Che',
+  'Wong Tai Sin',
+  'Yau Tong',
+  'Yau Yat Tsuen',
+  'Yuen Long',
+];

src/locales/en_HK/location/default_country.ts

@@ -0,0 +1 @@
+export default ['Hong Kong'];

src/locales/en_HK/location/index.ts

@@ -0,0 +1,34 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { LocationDefinitions } from '../../..';
+import building_number from './building_number';
+import city from './city';
+import default_country from './default_country';
+import postcode from './postcode';
+import postcode_by_state from './postcode_by_state';
+import state from './state';
+import state_abbr from './state_abbr';
+import street_cantonese_part from './street_cantonese_part';
+import street_english_part from './street_english_part';
+import street_pattern from './street_pattern';
+import street_prefix from './street_prefix';
+import street_suffix from './street_suffix';
+
+const location: LocationDefinitions = {
+  building_number,
+  city,
+  default_country,
+  postcode,
+  postcode_by_state,
+  state,
+  state_abbr,
+  street_cantonese_part,
+  street_english_part,
+  street_pattern,
+  street_prefix,
+  street_suffix,
+};
+
+export default location;

src/locales/en_HK/location/postcode.ts

@@ -0,0 +1,2 @@
+// https://www.hongkongpost.hk/en/about_us/tips/postcode/index.html
+export default null;

src/locales/en_HK/location/postcode_by_state.ts

@@ -0,0 +1,2 @@
+// https://www.hongkongpost.hk/en/about_us/tips/postcode/index.html
+export default null;

src/locales/en_HK/location/state.ts

@@ -0,0 +1 @@
+export default ['Hong Kong Island', 'Kowloon', 'New Territories'];

src/locales/en_HK/location/state_abbr.ts

@@ -0,0 +1 @@
+export default ['HK', 'KLN', 'NT'];