pronouny 0.1.1 → 0.3.0

package/README.md

@@ -4,47 +4,96 @@
 
 ## Installation
 
-To install, simply do `npm install pronouny`.
+To install, simply run `npm install pronouny`.
 
-## `Pronoun` class
+## Usage
 
-This class is intended to define individual `Pronoun`s. It includes subject, object, possessive adjective, possessive, and reflexive pronouns. It also contains a set of methods for extending, removing, and getting a pronoun string.
+```ts
+// Single import
+import Pronouny from 'pronouny';
 
-## `PronounSet` class
+// Create a new instance of the Validate class
+// All options are optional
+const p = new Pronouny({
+	// Will default to failing quietly into "they"
+	failQuietly: true,
+
+	// Will default to only querying the first subject
+	// pronoun to limit scope. Set to "true" to force
+	// recursive search.
+	deepSearch: false,
+
+	// Will default to using random pronouns in arrays.
+	// Set to false to force using 0 index.
+	useRandom: true,
+});
+
+// Create a new Pronoun object using Pronouny.new()
+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,
+// you can do it with Pronouny.add().
+p.add(pronounZe);
+
+// .remove() also works;
+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().
+//   ^Pronouny      ^PronounSet    ^Pronoun  ^string
+
+// Instantiate a set of pronouns using Pronouny.set().
+const vayne = {
+	username: "vaynegarden",
+	pronouns: p.set("she/ze/they"),
+};
+// 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`,
+// `psAdjective`, and `reflexive`.
+console.log(
+	`${vayne.username} has updated ${vayne.pronouns.psAdjective()} status.`
+);
+// This returns "vaynegarden updated her status", "vaynegarden
+// updated hir status", or "vaynegarden updated their status",
+// selected randomly among the three.
+```
 
-This class is intended to define `Pronoun`s for an individual or entity. It contains an array of `Pronoun`s, from which you can programmatically obtain a string using `use(type)`. `type` can be any of the five kinds from `Pronoun` (`sbj`, `obj`, `psAdj`, `psPrn`, and `rfx`).
+## Changelog
 
-## `Validate` class
+### v0.3.0
 
-This class is intended to verify and retrieve correct pronouns. It is centered around the `pronounSet` map, which is used to validate and return a `Pronoun` object using `resolvePronouns()` or `resolvePronounsStrict()`.
+-   Rewritten to consolidate functionality into a single default export `Pronouny`.
+-   Includes "we", "you", and "I" pronouns by default.
+-   Added a config object so you can decide on error handling globally.
+-   All methods are now chainable for ease of use.
 
-## Example
+### v0.2.0
 
-```
-import { Pronouny } from 'pronouny';
+-   Now fails silently when trying to resolve pronouns that don't exist or indexing out of bounds.
+-   Implementation of `PronounSet` class changed to Set from Array to prevent duplicate pronouns.
+-   added `get()` method to `PronounSet` class to retrieve a random Pronoun object.
+-   Added `add()` and `remove()` on `PronounSet`
 
-// Create a new instance of the Validate class
-const pronounValidator = new Pronouny.Validate();
+### v0.1.2
 
-// Create a new Pronoun object for ze/hir pronouns
-const pronounZe = new Pronouny.Pronoun(
-	'ze', 'hir', 'hir', 'hirs', 'hirself'
-);
+-   Initial release.
 
-// Add the pronoun to the pronounSet map
-pronounValidator.extend( "ze", pronounZe );
+## TODO
 
-// Set someone's pronouns.
-const vayne = {
-	username: vaynegarden,
-	pronouns: pronounValidator.createSetFrom( "she/ze/they"),
-}
-
-// Resolve the pronouns in your app
-console.log( vayne.username + " updated " +
-             vayne.pronouns.use( "psAdj" ) + " status." );
-// Returns "vaynegarden updated her status", "vaynegarden
-// updated hir status", or "vaynegarden updated their status",
-// selected randomly among the three.
+[ ] Full rewrite
 
-```
+-   [x] Consolidate implementation into one general-use class.
+-   [x] Add global configuration for pronoun use.
+-   [ ] Use more performant data structures.
+-   [ ] Cleaner error handling.
+-   [ ] Unique pronoun identifiers to allow for pronouns with the same first subject pronoun to have multiple forms.

package/lib/cjs/index.d.ts

@@ -1,247 +1,54 @@
-/**# Pronouny
- * A TypeScript library for pronoun validation and resolution.
- */
-export declare namespace Pronouny {
-    /**# Pronoun Class
-     * In order to construct a new `Pronoun`, you will need to pass in an
-     * object which contains at least one `subject` pronoun, one `object`
-     * pronoun, one `possessiveAdjective`, one `possessivePronoun`, and one
-     * `reflexive` pronoun. You may pass in a string (which will be
-     * automatically placed into an array of one) or an array.
-     *
-     * methods:
-     * * `new`: takes in an object containing the required pronouns.
-     * * `sbj`: returns subject pronouns. (e.g., he, she, they)
-     * * `obj`: returns object pronouns. (e.g., him, her, them)
-     * * `psAdj`: returns possessive adjectives (e.g., his, her, their)
-     * * `psPrn`: returns possessive pronouns (e.g., his, hers, theirs)
-     * * `rfx`: returns reflexive pronouns (e.g., himself, herself, themself)
-     */
-    class Pronoun {
-        subject: Array<string>;
-        object: Array<string>;
-        possessiveAdjective: Array<string>;
-        possessivePronoun: Array<string>;
-        reflexive: Array<string>;
-        /**
-         * # Pronoun Constructor
-         * In order to construct a new `Pronoun`, you will need to pass in an
-         * object which contains at least one `subject` pronoun, one `object`
-         * pronoun, one `possessiveAdjective`, one `possessivePronoun`, and one
-         * `reflexive` pronoun. You may pass in a string (which will be
-         * automatically placed into an array of one) or an array.
-         *
-         * @param pronouns
-         */
-        constructor(pronouns: {
-            subject: Array<string> | string;
-            object: Array<string> | string;
-            possessiveAdjective: Array<string> | string;
-            possessivePronoun: Array<string> | string;
-            reflexive: Array<string> | string;
-        });
-        /**## Subject Getter
-         * Retrieves a subject pronoun. If no index is provided, it will retrieve
-         * a random one from the array *(recommended)*.
-         *
-         * @throws if you index out of `subject` array length.
-         *
-         * @param index
-         * by default, selects randomly.
-         *
-         * @returns a string.
-         */
-        sbj(index?: number): string;
-        /**## Object Getter
-         * Retrieves an object pronoun. If no index is provided, it will retrieve
-         * a random one from the array *(recommended)*.
-         *
-         * @throws if you index out of `object` array length.
-         *
-         * @param index
-         * by default, selects randomly.
-         *
-         * @returns a string.
-         */
-        obj(index?: number): string;
-        /**## Possessive Adjective Getter
-         * Retrieves a possessive adjective pronoun. If no index is provided, it will retrieve
-         * a random one from the array *(recommended)*.
-         *
-         * @throws if you index out of `possessiveAdjective` array length.
-         *
-         * @param index
-         * by default, selects randomly.
-         *
-         * @returns a string.
-         */
-        psAdj(index?: number): string;
-        /**## Possessive Pronoun Getter
-         * Retrieves a possessive pronoun. If no index is provided, it will retrieve
-         * a random one from the array *(recommended)*.
-         *
-         * @throws if you index out of `possessivePronoun` array length.
-         *
-         * @param index
-         * by default, selects randomly.
-         *
-         * @returns a string.
-         */
-        psPrn(index?: number): string;
-        /**## Reflexive Pronoun Getter
-         * Retrieves a reflexive pronoun. If no index is provided, it will retrieve
-         * a random one from the array *(recommended)*.
-         *
-         * @throws if you index out of `reflexive` array length.
-         *
-         * @param index
-         * by default, selects randomly.
-         *
-         * @returns a string.
-         */
-        rfx(index?: number): string;
-        /**# Pronoun Extension
-         * Extend the set of Pronouns with new pronouns. You may pass in a
-         * string or an array of strings.
-         *
-         * @param pronounType
-         * Denotes which type of pronoun to extend. Can be `subject`, `object`,
-         * `possessiveAdjective`, `possessivePronoun`, or `reflexive`.
-         *
-         * @param extensions
-         * A string or array of strings to extend the pronoun set with.
-         */
-        extend(pronounType: "subject" | "object" | "possessiveAdjective" | "possessivePronoun" | "reflexive", extensions: string | Array<string>): void;
-        /**# Pronoun Removal
-         * Remove a pronoun from the set. You may pass in a string or
-         * an array of strings.
-         *
-         * @param pronounType
-         * Pronoun type to remove from. Can be `subject`, `object`,
-         * `possessiveAdjective`, `possessivePronoun`, or `reflexive`.
-         *
-         * @param removal
-         * Pronoun to remove from array. Can be a string or an array
-         * of strings.
-         */
-        remove(pronounType: "subject" | "object" | "possessiveAdjective" | "possessivePronoun" | "reflexive", removal: string | Array<string>): void;
-    }
-    /**# Pronoun Sets
-     * A class intended to define pronouns on a person.
-     */
-    class PronounSet {
-        pronouns: Array<Pronoun>;
-        /**# Pronoun Set Constructor
-         * Build a set of constructors either from an array of pronoun strings for resolution.
-         *
-         * @param validator
-         * Requires a `Pronouny.Validate` object to define valid pronouns for `PronounSet` construction.
-         *
-         * @param pronounString
-         * A string or array of strings for resolution. (e.g., "he/they", "she", "ze/faer")
-         *
-         * @param delimiter
-         * Defines the delimiter for string `pronounString`s.
-         *
-         * @param type
-         * Defines resolution type. `resolvePronoun` is recommended, though `resolvePronounStrict`
-         * will be faster if the format is well-defined.
-         */
-        constructor(validator: Validate, pronounString: string | Array<string>, delimiter?: string, type?: "resolvePronoun" | "resolvePronounStrict");
-        /**# Pronoun Retrieval
-         * Retrieves a pronoun from the given set.
-         *
-         * @param type
-         * Specifies the pronoun desired. Uses the same syntax as {@link Pronoun}'s getters.
-         * Use `sbj` for Subject, `obj` for Object, `psAdj` for Possessive Adjective, `psPrn`
-         * for Possessive Pronoun, and `rfx` for Reflexive.
-         *
-         * @param pronounIndex
-         * Specifies the index in the `PronounSet`. Defaults to a random one *(recommended)*.
-         *
-         * @param index
-         * Specifies the index in the `Pronoun`. Defaults to a random one *(recommended)*.
-         *
-         * @returns a string.
-         */
-        use(type: "sbj" | "obj" | "psAdj" | "psPrn" | "rfx", pronounIndex?: number, index?: number | undefined): string;
-    }
-    /**# Validator Class
-     * Validates and checks if the pronoun specified is valid. You may extend or
-     * remove Pronouns specified using the `extend()` or `remove()` methods.
-     */
-    class Validate {
-        pronounsSet: Map<string, Pronoun>;
-        /**# Validator Constructor
-         * Simply use `new Pronouny.Validate()` to create a new instance. It will
-         * be automatically populated with he, she, and they pronouns. Extend or
-         * otherwise modify it using `extend()` or `remove()`.
-         */
-        constructor();
-        /**# Pronoun Resolver
-         * Returns the Pronoun object for the given pronoun string. Will
-         * return `undefined` if the pronoun is not found.
-         *
-         * @param pronoun
-         * String to check for against `pronounsSet`.
-         *
-         * @returns a `Pronoun` object or `undefined`.
-         */
-        resolvePronoun(pronoun: string): Pronoun | undefined;
-        /**# Strict Pronoun Resolver
-         * Only checks the string against the `strictIdentifier` (usually
-         * the first subject pronoun). Returns the Pronoun object for the
-         * given pronoun string. Will return `undefined` if the pronoun is
-         * not found.
-         *
-         * @param pronoun
-         * String to check for against `pronounsSet`.
-         *
-         * @returns a `Pronoun` object or `undefined`.
-         */
-        resolvePronounStrict(pronoun: string): Pronoun | undefined;
-        /**# Pronoun Set Constructor
-         * Convenience method to build a `PronounSet` from a string or array of
-         * strings. You may specify a delimiter and resolution type.
-         *
-         * @param pronounString
-         * `string` or `Array<string>` to build the `PronounSet` from.
-         *
-         * @param delimiter
-         * delimiter to split the `pronounString` by.
-         *
-         * @param type
-         * determines the resolution type. `resolvePronoun` is recommended, though
-         * `resolvePronounStrict` will be faster if the format is well-defined.
-         *
-         * @returns a PronounSet.
-         */
-        createSetFrom(pronounString: string | Array<string>, delimiter?: string, type?: "resolvePronoun" | "resolvePronounStrict"): PronounSet;
-        /**# Pronoun Extension
-         * Extend the set of Pronouns with new pronouns. You may pass in a
-         * string or an array of strings.
-         *
-         * @param strictIdentifier
-         * The strict identifier for the pronoun set. Usually the first subject pronoun.
-         *
-         * @param pronoun
-         * A `Pronoun` object to extend the set with.
-         *
-         * @returns a `Pronoun` object.
-         */
-        extend(strictIdentifier: string, pronoun: Pronoun): void;
-        /**# Pronoun Removal
-         * Remove a `Pronoun` from the `pronounsSet` map. You may pass in a
-         * string or an array of strings.
-         *
-         * @param strictIdentifier
-         * The strict identifier for the pronoun set. Usually the first subject pronoun.
-         *
-         * @param pronoun
-         * A `Pronoun` object to extend the set with.
-         *
-         * @returns a `Pronoun` object.
-         */
-        remove(strictIdentifier: string, pronoun: Pronoun): void;
-    }
+declare class Pronoun {
+    sbj: Array<string>;
+    obj: Array<string>;
+    psv: Array<string>;
+    psj: Array<string>;
+    rfx: Array<string>;
+    constructor(pronouns: {
+        subject: Array<string> | string;
+        object: Array<string> | string;
+        possessive: Array<string> | string;
+        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;
 }
+declare class PronounSet {
+    pronouns: Set<Pronoun>;
+    resolver: Pronouny;
+    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;
+}
+type PronounyConfig = {
+    failQuietly?: boolean;
+    deepSearch?: boolean;
+    useRandom?: boolean;
+};
+export default class Pronouny {
+    config: PronounyConfig;
+    resolveMap: Map<string, Pronoun>;
+    constructor(config?: PronounyConfig);
+    resolve(pronoun: string, deepSearch?: boolean | undefined): Pronoun;
+    add(pronoun: Pronoun): this;
+    remove(pronoun: Pronoun): this;
+    set(pronouns: string | Array<string>, delimiter?: string): PronounSet;
+    new(pronouns: {
+        subject: Array<string> | string;
+        object: Array<string> | string;
+        possessive: Array<string> | string;
+        psAdjective: Array<string> | string;
+        reflexive: Array<string> | string;
+    }, autoAppend?: boolean): Pronoun;
+}
+export {};