namefully 1.1.0 → 1.2.1

package/readme.md

@@ -1,42 +1,49 @@
 # namefully
 
 [![npm version][version-img]][version-url]
-[![CircleCI][circleci-img]][circleci-url]
+[![JSR Version][jsr-version]][jsr-url]
+[![CI build][ci-img]][ci-url]
 [![Coverage Status][codecov-img]][codecov-url]
 [![MIT License][license-img]][license-url]
 
-## Description
-
-A JavaScript utility for handling person names.
+Human name handling made easy.
 [Try it live](https://stackblitz.com/edit/namefully).
 
 ## Documentation
 
 Check out the official documentation at
-[https://namefully.netlify.app](https://namefully.netlify.app/).
+[namefully.netlify.app](https://namefully.netlify.app).
 
 ## Motivation
 
 Have you ever had to format a user's name in a particular order, way, or shape?
 Probably yes. If not, it will come at some point. Be patient.
 
+You may want to use this library if:
+
+- you've been repeatedly dealing with users' given names and surnames;
+- you need to occasionally format a name in a particular order, way, or shape;
+- you keep copy-pasting your name-related business logic for every project;
+- you're curious about trying new, cool stuff.
+
 ## Key features
 
-1. Offer supports for Latin alphabet, including other European ones
-(e.g., German, Greek, Cyrillic, Icelandic characters)
-2. Accept different data shapes as input
-3. Use of optional parameters to access advanced features
-4. Format a name as desired
-5. Offer support for prefixes and suffixes
-6. Access to names' initials
-7. Allow hyphenated names, including with apostrophes
+1. Accept different data shapes as input
+2. Use optional parameters to access advanced features
+3. Format a name as desired
+4. Offer support for prefixes and suffixes
+5. Access to names' initials
+6. Support hyphenated names (and other special characters)
+7. Offer predefined validation rules for many writing systems, including the
+   Latin and European ones (e.g., German, Greek, Cyrillic, Icelandic characters)
 
 ## Advanced features
 
-1. Alter the order of appearance of a name: by given name or surname
-2. Handle various subparts of a surname and given name
+1. Alter the name order anytime
+2. Handle various parts of a surname and a given name
 3. Use tokens (separators) to reshape prefixes and suffixes
 4. Accept customized parsers (do it yourself)
+5. Parse non-standard name cases
 
 ## Installation
 
@@ -58,70 +65,84 @@ This package is also available in [Angular](https://angular.io/) and
 
 ## Usage
 
+See `example/example.ts`.
+
 ```ts
 import { Namefully } from 'namefully'
 
-const name = new Namefully('John Joe Smith')
-console.log(name.format('L, f m')) // => SMITH, John Joe
-console.log(name.zip()) // => John J. Smith
+const name = new Namefully('Thomas Alva Edison');
+console.log(name.short); // Thomas Edison
+console.log(name.public); // Thomas E
+console.log(name.initials()); // ['T', 'A', 'E']
+console.log(name.format('L, f m')); // EDISON, Thomas Alva
+console.log(name.zip()); // Thomas A. E.
 ```
 
-> NOTE: This package comes with its own declaration file for
-> [TypeScript](https://www.typescriptlang.org/) support.
+> NOTE: if you intend to use this utility for non-standard name cases such as
+> many middle names or last names, some extra work is required. For example,
+> using `Namefully.parse()` lets you parse names containing many middle names
+> with the risk of throwing a `NameError` when the parsing is not possible.
+
+## `Config` and default values
 
-## Options and default values
+`Config` is a single configuration to use across the other components.
+
+The multiton pattern is used to keep one configuration across the `Namefully`
+setup. This is useful for avoiding confusion when building other components such
+as `FirstName`, `LastName`, or `Name` of distinct types (or `Namon`) that may
+be of particular shapes.
 
 Below are enlisted the options supported by `namefully`.
 
 ### orderedBy
 
-`string: 'firstname' | 'lastname'`, default: `firstname`
+`NameOrder` - default: `NameOrder.FIRST_NAME`
 
-Indicate in what order the names appear when set as a raw string values or
-string array values. That is, the first element/piece of the name is either the
-given name (e.g., `Jon Snow`)  or the surname (e.g.,`Snow Jon`).
+Indicates in what order the names appear when set as raw string values or string
+array values. That is, the first element/piece of the name is either the given
+name (e.g., `Jon Snow`) or the surname (e.g.,`Snow Jon`).
 
 ```ts
 // 'Smith' is the surname in this raw string case
-const name = new Namefully('Smith John Joe', { orderedBy: 'lastname' })
-console.log(name.ln()) // => Smith
+const name1 = new Namefully('Smith John Joe', { orderedBy: NameOrder.LAST_NAME });
+console.log(name1.last); // Smith
 
 // 'Edison' is the surname in this string array case
-const name = new Namefully(['Edison', 'Thomas'], { orderedBy: 'lastname' })
-console.log(name.fn()) // => Thomas
+const name2 = new Namefully(['Edison', 'Thomas'], { orderedBy: NameOrder.LAST_NAME });
+console.log(name2.first); // Thomas
 ```
 
-> NOTE: This option also affects all the other results of the API. In other words,
-> the results will prioritize the order of appearance set in the first place for
-> the other operations. Keep in mind that in some cases, it can be altered on the
-> go. See the example below.
+> NOTE: This option also affects all the other results of the API. In other
+> words, the results will prioritize the order of appearance set in the first
+> place for the other operations. Keep in mind that in some cases, it can be
+> altered on the go. See the example below.
 
 ```ts
 // 'Smith' is the surname in this raw string case
-const name = new Namefully('Smith John Joe', { orderedBy: 'lastname' })
-console.log(name.full()) // => Smith John Joe
+const name = new Namefully('Smith John Joe', { orderedBy: NameOrder.LAST_NAME });
+console.log(name.fullName()); // Smith John Joe
 
 // Now alter the order by choosing the given name first
-console.log(name.full('firstname')) // => John Joe Smith
+console.log(name.fullName(NameOrder.FIRST_NAME)); // John Joe Smith
 ```
 
 ### separator
 
-`enum: Separator`, default: `Separator.SPACE`
+`Separator` - default: `Separator.SPACE`
 
-Only valid for raw string values, this option indicates how to split the parts of
-a raw string name under the hood.
+_Only valid for raw string values_, this option indicates how to split the parts
+of a raw string name under the hood.
 
 ```ts
-const name = new Namefully('Adam,Sandler', { separator: Separator.COMMA })
-console.log(name.full()) // => Adam Sandler
+const name = new Namefully('John,Smith', { separator: Separator.COMMA });
+console.log(name.full); // John Smith
 ```
 
-### titling
+### title
 
-`string: 'uk' | 'us'`, default: `uk`
+`Title` - default: `Title.UK`
 
-Abide by the ways the international community defines an abbreviated title.
+Abides by the ways the international community defines an abbreviated title.
 American and Canadian English follow slightly different rules for abbreviated
 titles than British and Australian English. In North American English, titles
 before a name require a period: `Mr., Mrs., Ms., Dr.`. In British and Australian
@@ -129,116 +150,107 @@ English, no periods are used in these abbreviations.
 
 ```ts
 const name = new Namefully({
-    prefix: 'Mr',
-    firstname: 'John',
-    lastname: 'Smith'
-}, { titling: 'us' })
-console.log(name.full()) // => Mr. John Smith
-console.log(name.px()) // => Mr.
+  prefix: 'Mr',
+  firstName: 'John',
+  lastName: 'Smith',
+}, { title: Title.US });
+console.log(name.full); // Mr. John Smith
+console.log(name.prefix); // Mr.
 ```
 
 ### ending
 
-`boolean`, default: `false`
+`boolean` - default: `false`
 
-Set an ending character after the full name (a comma before the suffix actually).
+Sets an ending character after the full name (a comma before the suffix actually).
 
 ```ts
 const name = new Namefully({
-    prefix: 'Mr',
-    firstname: 'John',
-    lastname: 'Smith',
-    suffix: 'PhD'
+    firstName: 'John',
+    lastName: 'Smith',
+    suffix: 'Ph.D'
 }, { ending: true })
-console.log(name.full()) // => Mr John Smith, PhD
+console.log(name.full) // John Smith, Ph.D
+console.log(name.suffix) // Ph.D
 ```
 
-### lastnameFormat
+### surname
 
-`string: 'father' | 'mother' | 'hyphenated' | 'all'`, default: `father`
+`Surname` - default: `Surname.FATHER`
 
-Defines the distinct formats to output a compound surname (e.g., Hispanic
-surnames).
+Defines the distinct formats to output a compound surname (e.g., Hispanic surnames).
 
 ```ts
-import { Namefully, Firstname, Lastname } from 'namefully'
-
-const fn = new Firstname('Jaden')
-const ln = new Lastname('Smith', 'Pinkett')
-const name = new Namefully([fn, ln], { lastnameFormat: 'hyphenated' })
-console.log(name.full()) // => Jaden Smith-Pinkett
+const name = new Namefully(
+    [new FirstName('John'), new LastName('Doe', 'Smith')],
+    { surname: Surname.HYPHENATED },
+);
+console.log(name.full); // John Doe-Smith
 ```
 
 ### bypass
 
-`boolean`, default: `false`
+`boolean` - default: `true`
 
-Skip all the validators (i.e., validation rules, regular expressions).
+Skips all the validators (i.e., validation rules, regular expressions).
 
 ```ts
-const name = new Namefully('2Pac Shakur', { bypass: true }) // normally would fail the regex
-console.log(name.fn()) // => 2Pac
+const name = new Namefully(
+  {
+    firstName: 'John',
+    lastName: 'Smith',
+    suffix: 'M.Sc.', // will fail the validation rule and throw an exception.
+  },
+  { bypass: false, ending: true },
+);
 ```
 
-> NOTE: This option can help to trick the utility and allow us to use it for
-> unsupported languages or inner contents like prefixes or suffixes. For example,
-> the Hindi characters will not pass the validation rules. Or, the Spanish
-> equivalent for `Mr` => `Sr` will raise an exception as it is not part of the
-> predefined prefixes.
+To sum it all up, the default values are:
 
-### parser
+```ts
+{
+    orderedBy: NameOrder.FIRST_NAME,
+    separator: Separator.SPACE,
+    title: Title.UK,
+    ending: false,
+    bypass: true,
+    surname: Surname.FATHER
+}
+```
 
-`object`, default: `null`
+## Do It Yourself
 
 Customize your own parser to indicate the full name yourself.
 
 ```ts
-import { Namefully, Firstname, Lastname, Parser } from 'namefully'
+import { Config, FullName, Namefully, Parser } from 'namefully'
 
 // Suppose you want to cover this '#' separator
-class MyParser implements Parser<string> {
-    constructor(public raw: string) {}
-    parse() {
-        const [fn, ln] = this.raw.split('#');
-        return {
-            firstname: new Firstname(fn),
-            lastname: new Lastname(ln),
-        }
+class SimpleParser extends Parser<string> {
+    parse(options: Partial<Config>): FullName {
+        const [firstName, lastName] = this.raw.split('#')
+        return FullName.parse({ firstName, lastName }, Config.merge(options))
     }
 }
 
-const name = new Namefully(null, { parser: new MyParser('Juan#Garcia') })
-console.log(name.full()) // => Juan Garcia
-```
-
-To sum up, the default values are:
-
-```json
-{
-    "orderedBy": "firstname",
-    "separator": " ",
-    "titling": "uk",
-    "ending": false,
-    "lastnameFormat": "father",
-    "bypass": false,
-    "parser": null
-}
+const name = new Namefully(new SimpleParser('Juan#Garcia'));
+console.log(name.full); // Juan Garcia
 ```
 
 ## Concepts and examples
 
-The name standards used for the current version of this library are as
-follows:
+The name standards used for the current version of this library are as follows:
 
-```[Prefix] Firstname [Middlename] Lastname [Suffix]```
+`[prefix] firstName [middleName] lastName [suffix]`
 
 The opening `[` and closing `]` brackets mean that these parts are optional. In
 other words, the most basic/typical case is a name that looks like this:
-`John Smith`, where `John` is the *Firstname* and `Smith`, the *Lastname*.
+`John Smith`, where `John` is the _firstName_ and `Smith`, the _lastName_.
 
-> NOTE: Do notice that the order of appearance matters and (as shown [here](#orderedBy))
-> can be altered through configured parameters. By default, the order of appearance
-> is as shown above and will be used as a basis for future examples and use cases.
+> NOTE: Do notice that the order of appearance matters and (as shown in
+> [orderedBy](#orderedby)) can be altered through configured parameters. By default,
+> the order of appearance is as shown above and will be used as a basis for
+> future examples and use cases.
 
 Once imported, all that is required to do is to create an instance of
 `Namefully` and the rest will follow.
@@ -247,74 +259,30 @@ Once imported, all that is required to do is to create an instance of
 
 Let us take a common example:
 
-```Mr John Joe Smith PhD```
+`Mr John Joe Smith PhD`
 
 So, this utility understands the name parts as follows:
 
-- typical name: `John Smith`
+- prefix: `Mr`
 - first name: `John`
 - middle name: `Joe`
 - last name: `Smith`
-- prefix: `Mr`
 - suffix: `PhD`
 - full name: `Mr John Joe Smith PhD`
 - birth name: `John Joe Smith`
-- zipped: `John J. Smith`
+- short version: `John Smith`
+- flattened: `John J. S.`
 - initials: `J J S`
-- usernames: `jsmith, johnsmith`, etc.
+- public: `John S`
 
 ### Limitations
 
 `namefully` does not have support for certain use cases:
 
-- mononame:  `Plato`. It can be tricked though by setting the mononame as both
-first and last name;
-- multiple surnames: `De La Cruz`, `Da Vinci`. You can also trick it using your
-own parsing method or setting separately each name part via the `Nama|Name` type
-or the string array input;
-- multiple prefixes: `Prof. Dr. Einstein`. An alternative would be to use the `bypass` option.
-
-See the [use cases](usecases) for further details.
-
-## API
-
-| Name | Arguments | Default | Returns | Description |
-|---|---|---|---|---|
-|*getPrefix*|none|none|`string`|Gets the prefix part of the full name, if any|
-|*getFirstname*|`includeAll`|`true`|`string`|Gets the first name part of the full name|
-|*getMiddlenames*|none|none|`string[]`|Gets the middle name part of the full name, if any|
-|*getLastname*|`format`|`null`|`string`|Gets the last name part of the full name|
-|*getSuffix*|none|none|`string`|Gets the suffix part of the full name, if any|
-|*getFullname*|`orderedBy`|`null`|`string`|Gets the full name|
-|*getBirthname*|`orderedBy`|`null`|`string`|Gets the birth name, no prefix or suffix|
-|*getInitials*|`orderedBy`, `withMid`|`null`, `false`|`string`|Gets the initials of the first and last names|
-|*describe*|`nameType`|`null`|`Summary`|Gives some descriptive statistics of the characters' distribution.|
-|*shorten*|`orderedBy`|`null`|`string`|Returns a typical name (e.g. first and last name)|
-|*compress*|`limit`, `by`|`20`, `middlename`|`string`|Compresses a name using different forms of variants|
-|*username*|none|none|`string[]`|Suggests possible (randomly) usernames closest to the name|
-|*format*|`how`|`null`|`string`|Formats the name as desired|
-|*zip*|`nameType`|`null`|`string`|Shortens a full name|
-|*size*|none|none|`number`|Returns the count of characters of the birth name, excluding punctuations|
-|*ascii*|`options`|`{}`|`number[]`|Returns an ascii representation of each characters|
-|*to*|`case`|none|`string`|Transforms a birth name to a specific title case|
-|*passwd*|`nameType`|`null`|`string`|Returns a password-like representation of a name|
-
-## Aliases
-
-If you find the names of the methods somewhat too long, we provide aliases to make
-your life easier as a coder.
-
-|Method|Aliases|
-|---|---|
-|*getPrefix*|*px*|
-|*getSuffix*|*sx*|
-|*getFirstname*|*fn*|
-|*getLastname*|*ln*|
-|*getMiddlenames*|*mn*|
-|*getFullname*|*full*|
-|*getBirthname*|*birth*|
-|*getInitials*|*inits*|
-|*describe*|*stats*|
+- mononame: `Plato`. A workaround is to set the mononame as both first and last name;
+- multiple prefixes: `Prof. Dr. Einstein`.
+
+See the [test cases](test) for further details.
 
 ## Author
 
@@ -322,14 +290,17 @@ Developed by [Ralph Florent](https://github.com/ralflorent).
 
 ## License
 
-The underlying content of this utility is licensed under [MIT](LICENSE).
+The underlying content of this utility is licensed under [MIT License](LICENSE).
 
 <!-- References -->
+
 [version-img]: https://img.shields.io/npm/v/namefully
 [version-url]: https://www.npmjs.com/package/namefully
-[circleci-img]: https://circleci.com/gh/ralflorent/namefully.svg?style=shield
-[circleci-url]: https://circleci.com/gh/ralflorent/namefully
-[codecov-img]: https://codecov.io/gh/ralflorent/namefully/branch/master/graph/badge.svg
+[jsr-version]: https://jsr.io/badges/@ralflorent/namefully
+[jsr-url]: https://jsr.io/@ralflorent/namefully
+[ci-img]: https://github.com/ralflorent/namefully/workflows/build/badge.svg
+[ci-url]: https://github.com/ralflorent/namefully/actions/workflows/ci.yml
+[codecov-img]: https://codecov.io/gh/ralflorent/namefully/branch/main/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/ralflorent/namefully
 [license-img]: https://img.shields.io/npm/l/namefully
 [license-url]: https://opensource.org/licenses/MIT

package/changelog.md

@@ -1,134 +0,0 @@
-# Changelog
-
-This file contains the documentation on the notable changes and bug fixes, and
-is formatted following this [standard](https://keepachangelog.com/en/1.0.0/).
-This project also adheres to [Semantic Versioning](https://semver.org/).
-
-## [1.1.0] - 2020-07-05
-
-**Added**:
-
-- Add a full name builder to construct `Namefully`
-- Augment a `namon` functionality
-  - capitalize
-  - decapitalize
-  - normalize
-  - reset
-- Add ASCII representations
-- Add password-like representations
-- Add support for title cases
-- Add support for birth names (full name without prefix or suffix)
-- Add test coverage for all the API methods
-- Update use cases for new features
-- Use string formats (`short`, `long`, `official`) when formatting a name
-
-**Fixed**:
-
-- Support space in regex
-- Use simplified regex
-- Support for more than one name parts in a first name
-- Revert changes in `compress(...)`: always include a token in the compressed part.
-- Switch to MIT License
-
-## [1.0.9] - 2020-05-18
-
-**Added**:
-
-- Add support for Cyrillic and Greek alphabet
-
-**Fixed**:
-
-- Fix validation rules (regex) for specific fields
-
-## [1.0.8] - 2020-04-18
-
-**Added**:
-
-- Add short API equivalent for `compress` => `zip`
-- Add `lastnameFormat` option to config and surname subparts handling
-- Refactor return values for `describe` (object instead of string)
-- Add support for titling when compressing or zipping
-
-**Fixed**:
-
-- Fix missing bypass for fullname validator
-- Fix logic for name parts handling in `Firstname` class
-
-## [1.0.7] - 2020-03-28
-
-**Added**:
-
-- Add `titling` option to config
-- Add support for prefixes and suffixes when formatting names
-  - including a clear cut for (de)-capitalized official names
-
-**Fixed**:
-
-- Fix wrong ending reference for suffixes
-
-## [1.0.6] - 2020-03-20
-
-**Added**:
-
-- Add support for Latin (European and Spanish) names
-- Add a bypass to skip validation rules (regex)
-
-## [1.0.5] - 2020-03-17
-
-**Added**:
-
-- Add optional parameters for the `getFullname` and `getInitials` API;
-  - Users can forcefully alter order of appearance the full name and initials;
-- Add optional parameters for the `describe` API;
-  - Users can either decide to describe the full name or some specific name parts;
-- Introduce new option in `Namefully` creation;
-  - `ending` accepts a separator for to mark an ending suffix;
-- Add some jsdoc comments to document the API;
-- Add some aliases to the API.
-
-**Fixed**:
-
-- Fix validation error for string array input using wrong/insufficient entries;
-- Fix options in `Namefully` creation;
-  - `orderedBy` accepts now two name parts only (first or last name);
-  - `separator` works as the splitting name factor;
-- Fix the order of appearance for the full name and `compress` API.
-
-## [1.0.3] - 2020-03-11
-
-**Fixed**:
-
-- Fix typescript compilation for ES2015, UMD
-- Fix `namefully` version
-
-## [1.0.2] - 2020-03-11
-
-**Added**:
-
-- Add use cases
-- Add test coverage
-- Add setup CI/CD
-- Add support for UMD
-- Make validation error message more explicit
-
-## [1.0.1] - 2020-03-07
-
-**Fixed**:
-
-- Fix typo in readme
-- Fix build system for npm
-
-## [1.0.0] - 2020-03-07
-
-Initial version
-
-[1.1.0]: https://github.com/ralflorent/namefully/compare/v1.0.9...v1.1.0
-[1.0.9]: https://github.com/ralflorent/namefully/compare/v1.0.8...v1.0.9
-[1.0.8]: https://github.com/ralflorent/namefully/compare/v1.0.7...v1.0.8
-[1.0.7]: https://github.com/ralflorent/namefully/compare/v1.0.6...v1.0.7
-[1.0.6]: https://github.com/ralflorent/namefully/compare/v1.0.5...v1.0.6
-[1.0.5]: https://github.com/ralflorent/namefully/compare/v1.0.3...v1.0.5
-[1.0.3]: https://github.com/ralflorent/namefully/compare/v1.0.2...v1.0.3
-[1.0.2]: https://github.com/ralflorent/namefully/compare/v1.0.1...v1.0.2
-[1.0.1]: https://github.com/ralflorent/namefully/compare/v1.0.0...v1.0.1
-[1.0.0]: https://github.com/ralflorent/namefully/releases/tag/v1.0.0

package/dist/lib/core/constants.d.ts

@@ -1,48 +0,0 @@
-/**
- * Constants
- *
- * Created on March 07, 2020
- * @author Ralph Florent <ralflornt@gmail.com>
- */
-import { Separator, Config, NameIndex } from '../models/index';
-import { CharSet } from './core';
-/**
- * The current version of `Namefully`.
- * @constant
- */
-export declare const version = "1.1.0";
-/**
- * CONFIG
- * @constant
- * @type {Config}
- * @default
- */
-export declare const CONFIG: Config;
-/**
- * NAME_INDEX
- * @constant
- * @type {NameIndex}
- * @default
- */
-export declare const NAME_INDEX: NameIndex;
-export declare const FIRST_LAST_NAME_INDEX = 2;
-export declare const LAST_FIRST_NAME_INDEX = 2;
-export declare const FIRST_MIDDLE_LAST_NAME_INDEX = 3;
-export declare const LAST_FIRST_MIDDLE_NAME_INDEX = 3;
-export declare const PREFIX_FIRST_MIDDLE_LAST_NAME_INDEX = 4;
-export declare const PREFIX_LAST_FIRST_MIDDLE_NAME_INDEX = 4;
-export declare const PREFIX_FIRST_MIDDLE_LAST_SUFFIX_NAME_INDEX = 5;
-export declare const PREFIX_LAST_FIRST_MIDDLE_SUFFIX_NAME_INDEX = 5;
-export declare const MIN_NUMBER_NAME_PART = 2;
-export declare const MAX_NUMBER_NAME_PART = 5;
-/**
- * RESTRICTED_CHARS
- * @constant
- * @default
- */
-export declare const RESTRICTED_CHARS: readonly [Separator.SPACE, Separator.SINGLE_QUOTE, Separator.HYPHEN, Separator.PERIOD, Separator.COMMA];
-/**
- * PASSWORD_MAPPER
- * @constant
- */
-export declare const PASSWORD_MAPPER: Map<string, CharSet<string>>;