pronouny 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Pronouny
 
-**Pronouny** is a typed library intended to make programmatically resolving English pronouns easier. It does so by providing three classes: `Pronoun`, `PronounSet` and `Validate`, each with their respective uses.
+**Pronouny** is a typed library intended to make programmatically resolving English pronouns easier.
 
 ## Installation
 
@@ -10,12 +10,12 @@ To install, simply run `npm install pronouny`.
 
 ```ts
 // Single import
-import Pronouny from 'pronouny';
+import Pronouny from "pronouny";
 
-// Create a new instance of the Validate class
-// All options are optional
+// Create a new instance of Pronouny. All config is optional.
+// Below are defaults.
 const p = new Pronouny({
-	// Will default to failing quietly into "they"
+	// Will default to failing quietly into "they".
 	failQuietly: true,
 
 	// Will default to only querying the first subject
@@ -26,16 +26,22 @@ const p = new Pronouny({
 	// Will default to using random pronouns in arrays.
 	// Set to false to force using 0 index.
 	useRandom: true,
+
+	// Will default to using "they" as a fallback pronoun.
+	fallbackPronoun: "they",
 });
 
 // Create a new Pronoun object using Pronouny.new()
-const pronounZe: Pronoun = p.new({
-	subject: "ze",
-	object: "hir",
-	possessive: "hirs",
-	psAdjective: "hir",
-	reflexive: "hirself",
-}, false);
+const pronounZe: Pronoun = p.new(
+	{
+		subject: "ze",
+		object: "hir",
+		possessive: "hirs",
+		psAdjective: "hir",
+		reflexive: "hirself",
+	},
+	false
+);
 
 // .new() will automatically add new Pronouns to its
 // validation map. however, if you want to do so manually,
@@ -46,8 +52,8 @@ p.add(pronounZe);
 p.remove(p.resolve("I"));
 // this deletes the "I" pronoun from the map.
 
-// Methods are chainable and you can reach the Pronoun class.
-p.add(pronounZe).set("he/they").use().subject().
+// Methods are chainable so you can reach the Pronoun class.
+p.add(pronounZe).set("he/they").use().subject();
 //   ^Pronouny      ^PronounSet    ^Pronoun  ^string
 
 // Instantiate a set of pronouns using Pronouny.set().
@@ -55,7 +61,7 @@ const vayne = {
 	username: "vaynegarden",
 	pronouns: p.set("she/ze/they"),
 };
-// from there, you can use `[PronounSet].use()` to get a random pronoun.
+// from there, you can use `[PronounSet].use()` to get a random `Pronoun`.
 
 // Resolve the pronouns in your app by referencing the form
 // that you need. There's `subject`, `object`, `possessive`,
@@ -70,6 +76,18 @@ console.log(
 
 ## Changelog
 
+### v0.4.0
+
+-   Optimized `forEach()` calls to use `for` loops instead.
+-   Added `fallbackPronoun` option to allow for configuration of pronoun to use in case of quiet failure states.
+-   Removed redundant `set` parameter from `[PronounSet].remove()` calls.
+
+### v0.3.1
+
+-   Added documentation.
+-   Reordered `failQuietly` and `useRandom` on `Pronoun`.
+-   Tested and fixed examples.
+
 ### v0.3.0
 
 -   Rewritten to consolidate functionality into a single default export `Pronouny`.
@@ -90,8 +108,6 @@ console.log(
 
 ## TODO
 
-[ ] Full rewrite
-
 -   [x] Consolidate implementation into one general-use class.
 -   [x] Add global configuration for pronoun use.
 -   [ ] Use more performant data structures.

package/lib/cjs/index.d.ts

@@ -1,9 +1,17 @@
+/**# `Pronoun` class
+ * A private class to construct the methods for pronoun
+ * access. Use {@link Pronouny} to create and
+ * append pronouns to the main validator. You can directly
+ * fetch pronoun arrays with `sbj`, `obj`, `psv`, `psj`,
+ * and `rfx`.
+ */
 declare class Pronoun {
     sbj: Array<string>;
     obj: Array<string>;
     psv: Array<string>;
     psj: Array<string>;
     rfx: Array<string>;
+    /** @constructor */
     constructor(pronouns: {
         subject: Array<string> | string;
         object: Array<string> | string;
@@ -11,38 +19,282 @@ declare class Pronoun {
         psAdjective: Array<string> | string;
         reflexive: Array<string> | string;
     });
-    subject(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
-    object(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
-    possessive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
-    psAdjective(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
-    reflexive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
+    /**# Subject Getter
+     * Get a subject pronoun. By default, uses one at
+     * random and fails silently by using the last
+     * pronoun if you index out of bounds.
+     *
+     * @param index
+     * Get `index`th pronoun, if specified. Fails to
+     * last if out of bounds and failing quietly.
+     * Default is `-1`.
+     *
+     * @param useRandom
+     * Overrides default random use behavior.
+     * Default is `true`.
+     *
+     * @param failQuietly
+     * Overrides default quiet failure behavior.
+     * Default is `true`.
+     */
+    subject(index?: number, useRandom?: boolean, failQuietly?: boolean): string;
+    /**# Object Getter
+     * Get an object pronoun. By default, uses one at
+     * random and fails silently by using the last
+     * pronoun if you index out of bounds.
+     *
+     * @param index
+     * Get `index`th pronoun, if specified. Fails to
+     * last if out of bounds and failing quietly.
+     * Default is `-1`.
+     *
+     * @param useRandom
+     * Overrides default random use behavior.
+     * Default is `true`.
+     *
+     * @param failQuietly
+     * Overrides default quiet failure behavior.
+     * Default is `true`.
+     */
+    object(index?: number, useRandom?: boolean, failQuietly?: boolean): string;
+    /**# Possessive Getter
+     * Get a possessive pronoun. By default, uses one
+     * at random and fails silently by using the last
+     * pronoun if you index out of bounds.
+     *
+     * @param index
+     * Get `index`th pronoun, if specified. Fails to
+     * last if out of bounds and failing quietly.
+     * Default is `-1`.
+     *
+     * @param useRandom
+     * Overrides default random use behavior.
+     * Default is `true`.
+     *
+     * @param failQuietly
+     * Overrides default quiet failure behavior.
+     * Default is `true`.
+     */
+    possessive(index?: number, useRandom?: boolean, failQuietly?: boolean): string;
+    /**# Possessive Adjective Getter
+     * Get a possessive adjective pronoun. By
+     * default, uses one at random and fails
+     * silently by using the last pronoun if you
+     * index out of bounds.
+     *
+     * @param index
+     * Get `index`th pronoun, if specified. Fails to
+     * last if out of bounds and failing quietly.
+     * Default is `-1`.
+     *
+     * @param useRandom
+     * Overrides default random use behavior.
+     * Default is `true`.
+     *
+     * @param failQuietly
+     * Overrides default quiet failure behavior.
+     * Default is `true`.
+     */
+    psAdjective(index?: number, useRandom?: boolean, failQuietly?: boolean): string;
+    /**# Reflexive Getter
+     * Get a reflexive pronoun. By default, uses one
+     * at random and fails silently by using the last
+     * pronoun if you index out of bounds.
+     *
+     * @param index
+     * Get `index`th pronoun, if specified. Fails to
+     * last if out of bounds and failing quietly.
+     * Default is `-1`.
+     *
+     * @param useRandom
+     * Overrides default random use behavior.
+     * Default is `true`.
+     *
+     * @param failQuietly
+     * Overrides default quiet failure behavior.
+     * Default is `true`.
+     */
+    reflexive(index?: number, useRandom?: boolean, failQuietly?: boolean): string;
 }
+/**# `PronounSet` class
+ * A private class to construct the methods on
+ * sets of pronouns. Use {@linkcode Pronouny.set()}
+ * to produce a PronounSet for an entity. You can
+ * add pronouns to a set using {@linkcode PronounSet.add()},
+ * remove them using {@linkcode PronounSet.remove()}
+ */
 declare class PronounSet {
     pronouns: Set<Pronoun>;
     resolver: Pronouny;
+    /** @constructor */
     constructor(resolver: Pronouny, pronouns?: Set<Pronoun> | Array<Pronoun> | Set<string> | Array<string> | string);
-    add(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean | undefined): this;
-    remove(set: PronounSet, pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean | undefined): this;
-    use(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): Pronoun;
-    subject(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
-    object(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
-    possessive(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
-    psAdjective(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
-    reflexive(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    /**# `.add()` to PronounSet
+     * Adds pronoun/s from a given Pronoun or strings
+     * (resolved using the {@linkcode Pronouny} instance
+     * used to create this PronounSet.)
+     *
+     * @param pronoun
+     * A string, Pronoun, or array of either, to be
+     * appended to the PronounSet.
+     *
+     * @param failQuietly
+     * Override default behavior to fail into 'they'.
+     */
+    add(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean): this;
+    /**# `.remove()` from PronounSet
+     * Remove pronoun/s from a given Pronoun or strings
+     * (resolved using the {@linkcode Pronouny} instance
+     * used to create this PronounSet.)
+     *
+     * @param pronoun
+     * A string, Pronoun, or array of either, to be
+     * appended to the PronounSet.
+     *
+     * @param failQuietly
+     * Override default behavior to fail into no removal.
+     */
+    remove(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean): this;
+    /**# `.use()` a PronounSet
+     * A method to retrieve one Pronoun at random. Use with
+     * {@link Pronoun|`Pronoun` methods} to get a specific
+     * form. You can also directly use {@link PronounSet.subject|`.subject()`},
+     * {@link PronounSet.object|`.object()`}, {@link PronounSet.possessive|`.possessive()`},
+     * {@link PronounSet.possessive|`.possessive()`}, or
+     * {@link PronounSet.reflexive|`.reflexive()`}. This is mostly
+     * here if you'd like to explicitly get a `Pronoun` instance
+     * from a `PronounSet`.
+     *
+     * @param index
+     * Retrieve `index`th pronoun from insertion.
+     *
+     * @param failQuietly
+     * Override default behavior to fail as per Pronouny config.
+     *
+     * @param useRandom
+     * Override default behavior to use random as per
+     * Pronouny config.
+     */
+    use(index?: number, failQuietly?: boolean, useRandom?: boolean): Pronoun;
+    /**Retrieves a random subject pronoun. */
+    subject(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
+    /**Retrieves a random object pronoun. */
+    object(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
+    /**Retrieves a random possessive pronoun. */
+    possessive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
+    /**Retrieves a random possessive adjective pronoun. */
+    psAdjective(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
+    /**Retrieves a random reflexive pronoun. */
+    reflexive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
 }
+/**# Config
+ * `failQuietly`: Controls various quiet failure states.
+ *
+ * `deepSearch`: Controls how deeply Pronouny will search
+ * for queries. By default, `string` parameters will
+ * only resolve using the first subject pronoun.
+ *
+ * `useRandom`: Controls whether random selection will be
+ * used. If false, it will default to 0. If failing
+ * quietly and indexing out of bounds, it will use the
+ * last item.
+ *
+ * `fallbackPronoun`: Controls what is considered the
+ * default pronoun for when one is not assigned or for
+ * quiet failure states. By default, this is `they`. **It
+ * is not recommended to change this.**
+ */
 type PronounyConfig = {
-    failQuietly?: boolean;
-    deepSearch?: boolean;
-    useRandom?: boolean;
+    /**Controls various quiet failure states. */
+    failQuietly: boolean;
+    /**Controls how deeply Pronouny will search for
+     * queries. By default, `string` parameters will
+     * only resolve using the first subject pronoun. */
+    deepSearch: boolean;
+    /**Controls whether random selection will be used.
+     * If false, it will default to 0. If failing
+     * quietly and indexing out of bounds, it will
+     * use the last item. */
+    useRandom: boolean;
+    /**Controls what is considered the default pronoun
+     * for when one is not assigned or for quiet failure
+     * states. By default, this is `they`. **It is not
+     * recommended to change this.**
+     *
+     * If you remove `they` from the Pronouny instance,
+     * you are responsible for setting this to a valid
+     * pronoun string and ensuring it will resolve. */
+    fallbackPronoun: string;
 };
+/**# Pronouny
+ * A typed library intended to make English pronoun
+ * resolution easy. Instantiate in your project using
+ * `new Pronouny()`, optionally passing in a
+ * {@link PronounyConfig|`PronounyConfig` object}.
+ *
+ * Once you have configured Pronouny, you may add new
+ * pronouns by using `new()` and passing in a set of
+ * pronouns. They are registered automatically. If you
+ * would like to register them manually, you can use
+ * `add()`. You can also `remove()` them if you would
+ * like to make them no longer valid.
+ *
+ * You can produce a {@linkcode PronounSet} by using
+ * `set()`. By passing in a string, it will
+ * automatically resolve each, using a delimiter if
+ * specified. From there, you can chain methods like
+ * `subject()` to retrieve a subject pronoun for use.
+ *
+ * If you would like to get a {@link Pronoun|`Pronoun` object}
+ * from a given text, you can use `resolve()`. Pass
+ * in a string and it will return the entire matched
+ * `Pronoun` object.
+ */
 export default class Pronouny {
     config: PronounyConfig;
     resolveMap: Map<string, Pronoun>;
     constructor(config?: PronounyConfig);
-    resolve(pronoun: string, deepSearch?: boolean | undefined): Pronoun;
+    /**# `.resolve()` a Pronoun
+     * Returns a pronoun from a given string. Uses
+     * Pronouny's config to determine the depth of search.
+     * By default, only checks the first subject pronoun.
+     */
+    resolve(pronoun: string, deepSearch?: boolean): Pronoun;
+    /**# `.add()` an Unlisted Pronoun
+     * If you made a `.new()` Pronoun but disabled
+     * `autoAppend`, you can later append it back by
+     * using this method. Returns `Pronouny`.
+     */
     add(pronoun: Pronoun): this;
+    /**# `.remove()` a Pronoun
+     * Renders a given Pronoun invalid within this
+     * Pronouny instance. Returns `Pronouny`.
+     */
     remove(pronoun: Pronoun): this;
+    /**# Make a `.set()` of Pronouns
+     * Returns a {@linkcode PronounSet} from a given
+     * string or array of strings. You can specify the
+     * delimiter to be used. By default, it is `/`.
+     */
     set(pronouns: string | Array<string>, delimiter?: string): PronounSet;
+    /**# `.new()`
+     * Returns a new pronoun. Takes in an object with
+     * a subject, object, possessive, possessive adjective,
+     * and reflexive string/s, and returns the Pronoun.
+     * By default, appends the new `Pronoun` to the Pronouny
+     * `resolveMap`.
+     *
+     * @param pronouns
+     * Takes an object with the structure of a `Pronoun`,
+     * with `Array<string>` or a `string` for `subject`,
+     * `object`, `possessive`, `psAdjective`, and
+     * `reflexive`.
+     *
+     * @param autoAppend
+     * Will automatically add the new Pronoun to the
+     * Pronouny instance. If false, will just return a
+     * {@link Pronoun|`Pronoun` object} without registering.
+     * You may register it later with {@link Pronouny.add}.
+     */
     new(pronouns: {
         subject: Array<string> | string;
         object: Array<string> | string;