feat: science module (#1014)

Co-authored-by: ST-DDT <[email protected]>
Co-authored-by: Shinigami <[email protected]>
Co-authored-by: pkuczynski <[email protected]>

10 files changed, 792 insertions, 0 deletions

diff --git a/src/definitions/definitions.ts b/src/definitions/definitions.ts
index 092c73a2..3ec795f7 100644
--- a/src/definitions/definitions.ts
+++ b/src/definitions/definitions.ts
@@ -12,6 +12,7 @@ import type { LoremDefinitions } from './lorem';
 import type { MusicDefinitions } from './music';
 import type { NameDefinitions } from './name';
 import type { PhoneNumberDefinitions } from './phone_number';
+import type { ScienceDefinitions } from './science';
 import type { SystemDefinitions } from './system';
 import type { VehicleDefinitions } from './vehicle';
 import type { WordDefinitions } from './word';
@@ -39,6 +40,7 @@ export interface Definitions {
   music: MusicDefinitions;
   name: NameDefinitions;
   phone_number: PhoneNumberDefinitions;
+  science: ScienceDefinitions;
   system: SystemDefinitions;
   vehicle: VehicleDefinitions;
   word: WordDefinitions;
diff --git a/src/definitions/index.ts b/src/definitions/index.ts
index 7341e241..03a68852 100644
--- a/src/definitions/index.ts
+++ b/src/definitions/index.ts
@@ -19,6 +19,7 @@ export type { LoremDefinitions } from './lorem';
 export type { MusicDefinitions } from './music';
 export type { NameDefinitions, NameTitleDefinitions } from './name';
 export type { PhoneNumberDefinitions } from './phone_number';
+export type { ScienceDefinitions } from './science';
 export type {
   SystemDefinitions,
   SystemMimeTypeEntryDefinitions,
diff --git a/src/definitions/science.ts b/src/definitions/science.ts
new file mode 100644
index 00000000..dbe35f4f
--- /dev/null
+++ b/src/definitions/science.ts
@@ -0,0 +1,16 @@
+import type { ChemicalElement, Unit } from '../modules/science';
+import type { LocaleEntry } from './definitions';
+
+/**
+ * The possible definitions related to science.
+ */
+export type ScienceDefinitions = LocaleEntry<{
+  /**
+   * Some science units.
+   */
+  unit: readonly Unit[];
+  /**
+   * Some periodic table element informtion.
+   */
+  chemicalElement: readonly ChemicalElement[];
+}>;
diff --git a/src/faker.ts b/src/faker.ts
index a252a3e0..d6a288c6 100644
--- a/src/faker.ts
+++ b/src/faker.ts
@@ -22,6 +22,7 @@ import { Music } from './modules/music';
 import { Name } from './modules/name';
 import { Phone } from './modules/phone';
 import { Random } from './modules/random';
+import { Science } from './modules/science';
 import { System } from './modules/system';
 import { Unique } from './modules/unique';
 import { Vehicle } from './modules/vehicle';
@@ -75,6 +76,7 @@ export class Faker {
   readonly music: Music = new Music(this);
   readonly name: Name = new Name(this);
   readonly phone: Phone = new Phone(this);
+  readonly science: Science = new Science(this);
   readonly system: System = new System(this);
   readonly vehicle: Vehicle = new Vehicle(this);
   readonly word: Word = new Word(this);
diff --git a/src/index.ts b/src/index.ts
index d437fd9d..48b21a05 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -21,6 +21,7 @@ export type {
   NameDefinitions,
   NameTitleDefinitions,
   PhoneNumberDefinitions,
+  ScienceDefinitions,
   SystemDefinitions,
   SystemMimeTypeEntryDefinitions,
   VehicleDefinitions,
@@ -38,6 +39,7 @@ export type {
 } from './modules/color';
 export { Gender } from './modules/name';
 export type { GenderType } from './modules/name';
+export { ChemicalElement, Unit } from './modules/science';
 export { Faker };
 
 // since we are requiring the top level of faker, load all locales by default
diff --git a/src/locales/en/index.ts b/src/locales/en/index.ts
index 75bd0437..0836cbab 100644
--- a/src/locales/en/index.ts
+++ b/src/locales/en/index.ts
@@ -20,6 +20,7 @@ import lorem from './lorem';
 import music from './music';
 import name_ from './name';
 import phone_number from './phone_number';
+import science from './science';
 import system from './system';
 import team from './team';
 import vehicle from './vehicle';
@@ -45,6 +46,7 @@ const en: LocaleDefinition = {
   music,
   name: name_,
   phone_number,
+  science,
   system,
   team,
   vehicle,
diff --git a/src/locales/en/science/chemicalElement.ts b/src/locales/en/science/chemicalElement.ts
new file mode 100644
index 00000000..06d84cf1
--- /dev/null
+++ b/src/locales/en/science/chemicalElement.ts
@@ -0,0 +1,592 @@
+export default Object.freeze([
+  {
+    symbol: 'H',
+    name: 'Hydrogen',
+    atomicNumber: 1,
+  },
+  {
+    symbol: 'He',
+    name: 'Helium',
+    atomicNumber: 2,
+  },
+  {
+    symbol: 'Li',
+    name: 'Lithium',
+    atomicNumber: 3,
+  },
+  {
+    symbol: 'Be',
+    name: 'Beryllium',
+    atomicNumber: 4,
+  },
+  {
+    symbol: 'B',
+    name: 'Boron',
+    atomicNumber: 5,
+  },
+  {
+    symbol: 'C',
+    name: 'Carbon',
+    atomicNumber: 6,
+  },
+  {
+    symbol: 'N',
+    name: 'Nitrogen',
+    atomicNumber: 7,
+  },
+  {
+    symbol: 'O',
+    name: 'Oxygen',
+    atomicNumber: 8,
+  },
+  {
+    symbol: 'F',
+    name: 'Fluorine',
+    atomicNumber: 9,
+  },
+  {
+    symbol: 'Ne',
+    name: 'Neon',
+    atomicNumber: 10,
+  },
+  {
+    symbol: 'Na',
+    name: 'Sodium',
+    atomicNumber: 11,
+  },
+  {
+    symbol: 'Mg',
+    name: 'Magnesium',
+    atomicNumber: 12,
+  },
+  {
+    symbol: 'Al',
+    name: 'Aluminium',
+    atomicNumber: 13,
+  },
+  {
+    symbol: 'Si',
+    name: 'Silicon',
+    atomicNumber: 14,
+  },
+  {
+    symbol: 'P',
+    name: 'Phosphorus',
+    atomicNumber: 15,
+  },
+  {
+    symbol: 'S',
+    name: 'Sulfur',
+    atomicNumber: 16,
+  },
+  {
+    symbol: 'Cl',
+    name: 'Chlorine',
+    atomicNumber: 17,
+  },
+  {
+    symbol: 'Ar',
+    name: 'Argon',
+    atomicNumber: 18,
+  },
+  {
+    symbol: 'K',
+    name: 'Potassium',
+    atomicNumber: 19,
+  },
+  {
+    symbol: 'Ca',
+    name: 'Calcium',
+    atomicNumber: 20,
+  },
+  {
+    symbol: 'Sc',
+    name: 'Scandium',
+    atomicNumber: 21,
+  },
+  {
+    symbol: 'Ti',
+    name: 'Titanium',
+    atomicNumber: 22,
+  },
+  {
+    symbol: 'V',
+    name: 'Vanadium',
+    atomicNumber: 23,
+  },
+  {
+    symbol: 'Cr',
+    name: 'Chromium',
+    atomicNumber: 24,
+  },
+  {
+    symbol: 'Mn',
+    name: 'Manganese',
+    atomicNumber: 25,
+  },
+  {
+    symbol: 'Fe',
+    name: 'Iron',
+    atomicNumber: 26,
+  },
+  {
+    symbol: 'Co',
+    name: 'Cobalt',
+    atomicNumber: 27,
+  },
+  {
+    symbol: 'Ni',
+    name: 'Nickel',
+    atomicNumber: 28,
+  },
+  {
+    symbol: 'Cu',
+    name: 'Copper',
+    atomicNumber: 29,
+  },
+  {
+    symbol: 'Zn',
+    name: 'Zinc',
+    atomicNumber: 30,
+  },
+  {
+    symbol: 'Ga',
+    name: 'Gallium',
+    atomicNumber: 31,
+  },
+  {
+    symbol: 'Ge',
+    name: 'Germanium',
+    atomicNumber: 32,
+  },
+  {
+    symbol: 'As',
+    name: 'Arsenic',
+    atomicNumber: 33,
+  },
+  {
+    symbol: 'Se',
+    name: 'Selenium',
+    atomicNumber: 34,
+  },
+  {
+    symbol: 'Br',
+    name: 'Bromine',
+    atomicNumber: 35,
+  },
+  {
+    symbol: 'Kr',
+    name: 'Krypton',
+    atomicNumber: 36,
+  },
+  {
+    symbol: 'Rb',
+    name: 'Rubidium',
+    atomicNumber: 37,
+  },
+  {
+    symbol: 'Sr',
+    name: 'Strontium',
+    atomicNumber: 38,
+  },
+  {
+    symbol: 'Y',
+    name: 'Yttrium',
+    atomicNumber: 39,
+  },
+  {
+    symbol: 'Zr',
+    name: 'Zirconium',
+    atomicNumber: 40,
+  },
+  {
+    symbol: 'Nb',
+    name: 'Niobium',
+    atomicNumber: 41,
+  },
+  {
+    symbol: 'Mo',
+    name: 'Molybdenum',
+    atomicNumber: 42,
+  },
+  {
+    symbol: 'Tc',
+    name: 'Technetium',
+    atomicNumber: 43,
+  },
+  {
+    symbol: 'Ru',
+    name: 'Ruthenium',
+    atomicNumber: 44,
+  },
+  {
+    symbol: 'Rh',
+    name: 'Rhodium',
+    atomicNumber: 45,
+  },
+  {
+    symbol: 'Pd',
+    name: 'Palladium',
+    atomicNumber: 46,
+  },
+  {
+    symbol: 'Ag',
+    name: 'Silver',
+    atomicNumber: 47,
+  },
+  {
+    symbol: 'Cd',
+    name: 'Cadmium',
+    atomicNumber: 48,
+  },
+  {
+    symbol: 'In',
+    name: 'Indium',
+    atomicNumber: 49,
+  },
+  {
+    symbol: 'Sn',
+    name: 'Tin',
+    atomicNumber: 50,
+  },
+  {
+    symbol: 'Sb',
+    name: 'Antimony',
+    atomicNumber: 51,
+  },
+  {
+    symbol: 'Te',
+    name: 'Tellurium',
+    atomicNumber: 52,
+  },
+  {
+    symbol: 'I',
+    name: 'Iodine',
+    atomicNumber: 53,
+  },
+  {
+    symbol: 'Xe',
+    name: 'Xenon',
+    atomicNumber: 54,
+  },
+  {
+    symbol: 'Cs',
+    name: 'Caesium',
+    atomicNumber: 55,
+  },
+  {
+    symbol: 'Ba',
+    name: 'Barium',
+    atomicNumber: 56,
+  },
+  {
+    symbol: 'La',
+    name: 'Lanthanum',
+    atomicNumber: 57,
+  },
+  {
+    symbol: 'Ce',
+    name: 'Cerium',
+    atomicNumber: 58,
+  },
+  {
+    symbol: 'Pr',
+    name: 'Praseodymium',
+    atomicNumber: 59,
+  },
+  {
+    symbol: 'Nd',
+    name: 'Neodymium',
+    atomicNumber: 60,
+  },
+  {
+    symbol: 'Pm',
+    name: 'Promethium',
+    atomicNumber: 61,
+  },
+  {
+    symbol: 'Sm',
+    name: 'Samarium',
+    atomicNumber: 62,
+  },
+  {
+    symbol: 'Eu',
+    name: 'Europium',
+    atomicNumber: 63,
+  },
+  {
+    symbol: 'Gd',
+    name: 'Gadolinium',
+    atomicNumber: 64,
+  },
+  {
+    symbol: 'Tb',
+    name: 'Terbium',
+    atomicNumber: 65,
+  },
+  {
+    symbol: 'Dy',
+    name: 'Dysprosium',
+    atomicNumber: 66,
+  },
+  {
+    symbol: 'Ho',
+    name: 'Holmium',
+    atomicNumber: 67,
+  },
+  {
+    symbol: 'Er',
+    name: 'Erbium',
+    atomicNumber: 68,
+  },
+  {
+    symbol: 'Tm',
+    name: 'Thulium',
+    atomicNumber: 69,
+  },
+  {
+    symbol: 'Yb',
+    name: 'Ytterbium',
+    atomicNumber: 70,
+  },
+  {
+    symbol: 'Lu',
+    name: 'Lutetium',
+    atomicNumber: 71,
+  },
+  {
+    symbol: 'Hf',
+    name: 'Hafnium',
+    atomicNumber: 72,
+  },
+  {
+    symbol: 'Ta',
+    name: 'Tantalum',
+    atomicNumber: 73,
+  },
+  {
+    symbol: 'W',
+    name: 'Tungsten',
+    atomicNumber: 74,
+  },
+  {
+    symbol: 'Re',
+    name: 'Rhenium',
+    atomicNumber: 75,
+  },
+  {
+    symbol: 'Os',
+    name: 'Osmium',
+    atomicNumber: 76,
+  },
+  {
+    symbol: 'Ir',
+    name: 'Iridium',
+    atomicNumber: 77,
+  },
+  {
+    symbol: 'Pt',
+    name: 'Platinum',
+    atomicNumber: 78,
+  },
+  {
+    symbol: 'Au',
+    name: 'Gold',
+    atomicNumber: 79,
+  },
+  {
+    symbol: 'Hg',
+    name: 'Mercury',
+    atomicNumber: 80,
+  },
+  {
+    symbol: 'Tl',
+    name: 'Thallium',
+    atomicNumber: 81,
+  },
+  {
+    symbol: 'Pb',
+    name: 'Lead',
+    atomicNumber: 82,
+  },
+  {
+    symbol: 'Bi',
+    name: 'Bismuth',
+    atomicNumber: 83,
+  },
+  {
+    symbol: 'Po',
+    name: 'Polonium',
+    atomicNumber: 84,
+  },
+  {
+    symbol: 'At',
+    name: 'Astatine',
+    atomicNumber: 85,
+  },
+  {
+    symbol: 'Rn',
+    name: 'Radon',
+    atomicNumber: 86,
+  },
+  {
+    symbol: 'Fr',
+    name: 'Francium',
+    atomicNumber: 87,
+  },
+  {
+    symbol: 'Ra',
+    name: 'Radium',
+    atomicNumber: 88,
+  },
+  {
+    symbol: 'Ac',
+    name: 'Actinium',
+    atomicNumber: 89,
+  },
+  {
+    symbol: 'Th',
+    name: 'Thorium',
+    atomicNumber: 90,
+  },
+  {
+    symbol: 'Pa',
+    name: 'Protactinium',
+    atomicNumber: 91,
+  },
+  {
+    symbol: 'U',
+    name: 'Uranium',
+    atomicNumber: 92,
+  },
+  {
+    symbol: 'Np',
+    name: 'Neptunium',
+    atomicNumber: 93,
+  },
+  {
+    symbol: 'Pu',
+    name: 'Plutonium',
+    atomicNumber: 94,
+  },
+  {
+    symbol: 'Am',
+    name: 'Americium',
+    atomicNumber: 95,
+  },
+  {
+    symbol: 'Cm',
+    name: 'Curium',
+    atomicNumber: 96,
+  },
+  {
+    symbol: 'Bk',
+    name: 'Berkelium',
+    atomicNumber: 97,
+  },
+  {
+    symbol: 'Cf',
+    name: 'Californium',
+    atomicNumber: 98,
+  },
+  {
+    symbol: 'Es',
+    name: 'Einsteinium',
+    atomicNumber: 99,
+  },
+  {
+    symbol: 'Fm',
+    name: 'Fermium',
+    atomicNumber: 100,
+  },
+  {
+    symbol: 'Md',
+    name: 'Mendelevium',
+    atomicNumber: 101,
+  },
+  {
+    symbol: 'No',
+    name: 'Nobelium',
+    atomicNumber: 102,
+  },
+  {
+    symbol: 'Lr',
+    name: 'Lawrencium',
+    atomicNumber: 103,
+  },
+  {
+    symbol: 'Rf',
+    name: 'Rutherfordium',
+    atomicNumber: 104,
+  },
+  {
+    symbol: 'Db',
+    name: 'Dubnium',
+    atomicNumber: 105,
+  },
+  {
+    symbol: 'Sg',
+    name: 'Seaborgium',
+    atomicNumber: 106,
+  },
+  {
+    symbol: 'Bh',
+    name: 'Bohrium',
+    atomicNumber: 107,
+  },
+  {
+    symbol: 'Hs',
+    name: 'Hassium',
+    atomicNumber: 108,
+  },
+  {
+    symbol: 'Mt',
+    name: 'Meitnerium',
+    atomicNumber: 109,
+  },
+  {
+    symbol: 'Ds',
+    name: 'Darmstadtium',
+    atomicNumber: 110,
+  },
+  {
+    symbol: 'Rg',
+    name: 'Roentgenium',
+    atomicNumber: 111,
+  },
+  {
+    symbol: 'Cn',
+    name: 'Copernicium',
+    atomicNumber: 112,
+  },
+  {
+    symbol: 'Nh',
+    name: 'Nihonium',
+    atomicNumber: 113,
+  },
+  {
+    symbol: 'Fl',
+    name: 'Flerovium',
+    atomicNumber: 114,
+  },
+  {
+    symbol: 'Mc',
+    name: 'Moscovium',
+    atomicNumber: 115,
+  },
+  {
+    symbol: 'Lv',
+    name: 'Livermorium',
+    atomicNumber: 116,
+  },
+  {
+    symbol: 'Ts',
+    name: 'Tennessine',
+    atomicNumber: 117,
+  },
+  {
+    symbol: 'Og',
+    name: 'Oganesson',
+    atomicNumber: 118,
+  },
+]);
diff --git a/src/locales/en/science/index.ts b/src/locales/en/science/index.ts
new file mode 100644
index 00000000..a28238b1
--- /dev/null
+++ b/src/locales/en/science/index.ts
@@ -0,0 +1,14 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+import type { ScienceDefinitions } from '../../..';
+import chemicalElement from './chemicalElement';
+import unit from './unit';
+
+const science: ScienceDefinitions = {
+  chemicalElement,
+  unit,
+};
+
+export default science;
diff --git a/src/locales/en/science/unit.ts b/src/locales/en/science/unit.ts
new file mode 100644
index 00000000..7390c983
--- /dev/null
+++ b/src/locales/en/science/unit.ts
@@ -0,0 +1,90 @@
+export default Object.freeze([
+  {
+    name: 'meter',
+    symbol: 'm',
+  },
+  {
+    name: 'second',
+    symbol: 's',
+  },
+  {
+    name: 'mole',
+    symbol: 'mol',
+  },
+  {
+    name: 'ampere',
+    symbol: 'A',
+  },
+  {
+    name: 'kelvin',
+    symbol: 'K',
+  },
+  {
+    name: 'candela',
+    symbol: 'cd',
+  },
+  {
+    name: 'kilogram',
+    symbol: 'kg',
+  },
+  {
+    name: 'radian',
+    symbol: 'rad',
+  },
+  {
+    name: 'hertz',
+    symbol: 'Hz',
+  },
+  {
+    name: 'newton',
+    symbol: 'N',
+  },
+  {
+    name: 'pascal',
+    symbol: 'Pa',
+  },
+  {
+    name: 'joule',
+    symbol: 'J',
+  },
+  {
+    name: 'watt',
+    symbol: 'W',
+  },
+  {
+    name: 'coulomb',
+    symbol: 'C',
+  },
+  {
+    name: 'volt',
+    symbol: 'V',
+  },
+  {
+    name: 'ohm',
+    symbol: 'Ω',
+  },
+  {
+    name: 'tesla',
+    symbol: 'T',
+  },
+  {
+    name: 'degree Celsius',
+    symbol: '°C',
+  },
+  {
+    name: 'lumen',
+    symbol: 'lm',
+  },
+  {
+    name: 'becquerel',
+    symbol: 'Bq',
+  },
+  {
+    name: 'gray',
+    symbol: 'Gy',
+  },
+  {
+    name: 'sievert',
+    symbol: 'Sv',
+  },
+]);
diff --git a/src/modules/science/index.ts b/src/modules/science/index.ts
new file mode 100644
index 00000000..1f5e042a
--- /dev/null
+++ b/src/modules/science/index.ts
@@ -0,0 +1,71 @@
+import type { Faker } from '../..';
+
+/**
+ * The possible definitions related to elements.
+ */
+export interface ChemicalElement {
+  /**
+   * The symbol for the element (e.g. `'He'`).
+   */
+  symbol: string;
+  /**
+   * The name for the element (e.g. `'Cerium'`).
+   */
+  name: string;
+  /**
+   * The atomic number for the element (e.g. `52`).
+   */
+  atomicNumber: number;
+}
+
+export interface Unit {
+  /**
+   * The long version of the unit (e.g. `meter`).
+   */
+  name: string;
+  /**
+   * The short version/abbreviation of the element (e.g. `Pa`).
+   */
+  symbol: string;
+}
+
+/**
+ * Module to generate science related entries.
+ */
+export class Science {
+  constructor(private readonly faker: Faker) {
+    // Bind `this` so namespaced is working correctly
+    for (const name of Object.getOwnPropertyNames(Science.prototype)) {
+      if (name === 'constructor' || typeof this[name] !== 'function') {
+        continue;
+      }
+      this[name] = this[name].bind(this);
+    }
+  }
+
+  /**
+   * Returns a random periodic table element.
+   *
+   * @example
+   * faker.science.chemicalElement() // { symbol: 'H', name: 'Hydrogen', atomicNumber: 1 }
+   * faker.science.chemicalElement() // { symbol: 'Xe', name: 'Xenon', atomicNumber: 54 }
+   * faker.science.chemicalElement() // { symbol: 'Ce', name: 'Cerium', atomicNumber: 58 }
+   */
+  chemicalElement(): ChemicalElement {
+    return this.faker.helpers.arrayElement(
+      this.faker.definitions.science.chemicalElement
+    );
+  }
+
+  /**
+   * Returns a random scientific unit.
+   *
+   * @example
+   * faker.science.unit() // { name: 'meter', symbol: 'm' }
+   * faker.science.unit() // { name: 'second', symbol: 's' }
+   * faker.science.unit() // { name: 'mole', symbol: 'mol' }
+   */
+  unit(): Unit {
+    return this.faker.helpers.arrayElement(this.faker.definitions.science.unit);
+  }
+}