Merge branch 'next' into chore/remove-TODOs

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

@@ -6,6 +6,7 @@ export interface ApiDocsMethod {
   readonly parameters: ApiDocsMethodParameter[];
   readonly returns: string;
   readonly throws: string | undefined; // HTML
+  readonly signature: string; // HTML
   readonly examples: string; // HTML
   readonly seeAlsos: string[];
   readonly sourcePath: string; // URL-Suffix

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

@@ -40,6 +40,9 @@ function seeAlsoToUrl(see: string): string {
       <strong>Throws:</strong> <span v-html="props.method.throws" />
     </p>
 
+    <div v-html="props.method.signature" />
+
+    <h3>Examples</h3>
     <div v-html="props.method.examples" />
 
     <div v-if="props.method.seeAlsos.length > 0">

docs/guide/upgrading.md

@@ -349,6 +349,24 @@ const city = enforcer.enforce(faker.location.city, {
 `enforce-unique` does not directly support the `store` option previously available in `faker.helpers.unique`. If you were previously using this parameter, check the [documentation](https://www.npmjs.com/package/enforce-unique). If you need to reset the store, you can call the `reset()` method on the `UniqueEnforcer` instance.
 :::
 
+#### `faker.helpers.arrayElement` and `faker.helpers.arrayElements`
+
+The following only affects usage in Javascript, as in Typescript this usage would already throw a compile-time error.
+
+Previously, the `arrayElement` and `arrayElements` methods would throw a dedicated error, when called without arguments.
+
+```ts
+faker.helpers.arrayElement(undefined); // FakerError: Calling `faker.helpers.arrayElement()` without arguments is no longer supported.
+```
+
+Now, it throws a JS native error:
+
+```ts
+faker.helpers.arrayElement(undefined); // TypeError: Cannot read properties of undefined (reading 'length')
+```
+
+Calling the methods with an empty array instead still behaves as before.
+
 ### Image Module
 
 Removed deprecated image methods
@@ -567,6 +585,15 @@ Now, this throws an error raising awareness of that bad value.
 
 This affects the `refDate` parameter of the `anytime()`, `birthdate()`, `past()`, `future()`, `recent()` and `soon()`, methods as well as the `from` and `to` parameters of `between()` and `betweens()`.
 
+### Separate Timezone Methods
+
+The `timeZone` functionality has been divided to enhance specificity:
+
+- Use `faker.date.timeZone()` to generate a random global time zone.
+- Use `faker.location.timeZone()` to obtain time zone specific to the current locale.
+
+We haven't updated all locale dependent time zone data yet, so if you encounter unexpected values, please create a new issue.
+
 ### Prices Now Return More Price-Like Values
 
 The `faker.commerce.price()` method now produces values that also return fractional values.

scripts/apidocs/output/page.ts

@@ -165,7 +165,8 @@ async function toMethodData(method: RawApiDocsMethod): Promise<ApiDocsMethod> {
     sourcePath: `${filePath}#L${line}`,
     throws: throws.length === 0 ? undefined : mdToHtml(throws.join('\n'), true),
     returns: returns.text,
-    examples: codeToHtml([formattedSignature, ...examples].join('\n')),
+    signature: codeToHtml(formattedSignature),
+    examples: codeToHtml(examples.join('\n')),
     deprecated: mdToHtml(deprecated),
     seeAlsos: seeAlsos.map((seeAlso) => mdToHtml(seeAlso, true)),
   };

src/definitions/date.ts

@@ -13,6 +13,15 @@ export type DateDefinition = LocaleEntry<{
    * The translations for weekdays (Sunday - Saturday).
    */
   weekday: DateEntryDefinition;
+
+  /**
+   * The names of the IANA time zones. Not tied to the current locale.
+   *
+   * Since this is the same for all locales, it is only defined in the `base` locale.
+   *
+   * @see [IANA Time Zone Database](https://www.iana.org/time-zones)
+   */
+  time_zone: string[];
 }>;
 
 /**

src/definitions/location.ts

@@ -137,7 +137,9 @@ export type LocationDefinition = LocaleEntry<{
   secondary_address: string[];
 
   /**
-   * A list of timezones names.
+   * A list of time zones names relevant to this locale.
+   *
+   * @see [IANA Time Zone Database](https://www.iana.org/time-zones)
    */
   time_zone: string[];
 }>;

src/locales/base/date/index.ts

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