add class-transformer, etc

Signed-off-by: Bruce D'Arcus <bdarcus@gmail.com>

examples/style.csl.yaml

@@ -3,6 +3,8 @@
 # this is a flatter model, relying more heavily on parameters
 title: APA
 options:
+  dateFormatting:
+    month: short # all are optional, and set reasonable defaults
   sort:
     - key: author
       order: ascending
@@ -11,16 +13,13 @@ options:
   group:
     # be explicit about grouping, which is core logic
     - key: author
-      # not sure on details here yet, but basic idea is disambiguation 
-      # is related to grouping
-      disambiguate:
-        addNames: all-with-initials
     - key: year
-      disambiguate:
-        addYearSuffix: true
   # pave the way for multilingual support
   localization:
     scope: global
+  disambiguate:
+    addNames: all-with-initials
+    addYearSuffix: true
   # again: put this on a parameter
   substitute:
     author:

package.json

@@ -14,23 +14,23 @@
     "start:ci": "node ./build/esbuild.js --run",
     "start:prod": "node ./build/esbuild.js --watch --run"
   },
-  "prettier": "./.prettierrc.json",
+  "types": "./types/index.d.ts",
+  "dependencies": {},
   "devDependencies": {
     "@es-exec/esbuild-plugin-start": "^0.0.4",
     "@types/node": "^18.14.1",
     "@typescript-eslint/eslint-plugin": "^5.53.0",
     "@typescript-eslint/parser": "^5.53.0",
     "class-transformer": "^0.5.1",
-    "edtf": "^4.4.1",
     "esbuild": "^0.17.10",
-    "eslint-config-prettier": "^8.6.0",
     "minimist": "^1.2.8",
     "rome": "^12.0.0",
     "typedoc": "^0.24.6",
     "typescript": "^4.9.5",
     "typescript-json-schema": "^0.56.0"
   },
   "dependencies": {
-    "yaml": "^2.2.2"
+    "yaml": "^2.2.2",
+    "edtf": "^4.4.1"
   }
 }

src/bibliography.ts

@@ -1,24 +1,60 @@
+import { Type } from "class-transformer";
+import { Reference } from "./reference";
 
-import { Reference } from './reference';
-
+/**
+ * A bibliography is a collection of references.
+ *
+ * It is the input of a citation processor.
+ *
+ * @examples
+ * {
+ * "title": "My Bibliography",
+ * "description": "A collection of references.",
+ * "references": [
+ *   {
+ *     "id": "doe1",
+ *     "type": "book",
+ *    "title": "The Title",
+ *     "author": [
+ *       {
+ *         "family": "Doe",
+ *         "given": "Jane"
+ *       }
+ *     ],
+ *     "issued": "2023"
+ *   }
+ * ]
+ *}
+ */
 export class Bibliography {
-  title?: string;
-  description?: string;
-  references: Reference[];
+	/**
+	 * The title of the bibliography.
+	 */
+	title?: string;
+	/**
+	 * The description of the bibliography.
+	 */
+	description?: string;
 
-  constructor(title?: string, description?: string) {
-    this.title = title;
-    this.description = description;
-    this.references = [];
-  }
+	/**
+	 * The references array.
+	 *
+	 * @items.minimum 1
+	 */
+	@Type(() => Reference)
+	references: Reference[];
 
-  addReference(reference: Reference): void {
-    this.references.push(reference);
-  }
+	constructor(title?: string, description?: string) {
+		this.title = title;
+		this.description = description;
+		this.references = [];
+	}
 
-  addReferences(references: Reference[]): void {
-    this.references = this.references.concat(references);
-  }
-
-}
+	addReference(reference: Reference): void {
+		this.references.push(reference);
+	}
 
+	addReferences(references: Reference[]): void {
+		this.references = this.references.concat(references);
+	}
+}

src/citation.ts

@@ -1,71 +1,69 @@
-
-import { Locale } from './locale';
-import { ID } from './reference';
-
-type CitationModeType = "integral" | "nonIntegral";
-
-export type Citation = {
-  /**
-   * Local citation rendering option; aka command or style.
-   * 
-   * - `integral` places the author inline in the text; also known as "narrative" or "in text" citations.
-   * - `nonIntegral` places the author in the citation.
-   * 
-   * Both are more general than author-date styles, and can apply to any citation style.
-   * 
-   * @default nonIntegral // REVIEW this is current CSL behavior, but should it be? Remove the default altogether?
-   * 
-   */
-  mode?: CitationModeType;
-  /**
-   * The string that prefaces a list of citation references.
-   */
-  // richer than CSL 1.0, but matches biblatex/org-cite
-  prefix?: string;
-  /**
-   * The string that follows a list of citation references.   
-   */
-  suffix?: string;
-  references: CiteRef[];
-}
-
-
-export type CiteRef = {
-  /**
-   * A string that prefaces the citation reference.
-   */
-  prefix?: string;
-  /**
-   * The unique identifier token for the citation reference.
-   */
-  refID: ID;
-  /**
-   * A string that follows the citation reference.
-   * 
-   * CSL styles recognize "locator" in citation references' suffix. For example, in the citation
-   *
-   *    [cite:see @Tarski-1965 chapter 1, for an example]
-   * 
-   * "chapter 1" is the locator.  The whole citation is rendered as
-   *
-   *    (see Tarski 1965, chap. 1 for an example)
-   *
-   * in the default CSL style.
-   *
-   * The locator starts with a locator term listed in the LocatorTerms type.
-   * The locator term is followed by a space and then the locator value. 
-   * The locator value is a string of numbers and/or letters.  
-   * The locator value may be discontinuous, in which case it is separated by commas. For example, "23, 25-36" 
-   * is a discontinuous locator value.
-   *
-   * The part of the suffix before the locator is appended to reference's prefix.
-   * If no locator term is used, but a number is present, then "page" is assumed.
-   * 
-   * Adapted from org-mode.
-   * 
-   * See also https://pandoc.org/MANUAL.html#extension-citations   
-   */
-  // REVIEW: the above will fail in some cases, with pandoc syntax offering a fail safe of sorts.
-  // An alernative, more robust, approach is to use a structured array, as in the v1.1 branch.
-  suffix?: string;
-}
+import { Locale } from "./locale";
+import { ID } from "./reference";
+
+type CitationModeType = "integral" | "nonIntegral";
+
+export type Citation = {
+	/**
+	 * Local citation rendering option; aka command or style.
+	 *
+	 * - `integral` places the author inline in the text; also known as "narrative" or "in text" citations.
+	 * - `nonIntegral` places the author in the citation.
+	 *
+	 * Both are more general than author-date styles, and can apply to any citation style.
+	 *
+	 * @default nonIntegral // REVIEW this is current CSL behavior, but should it be? Remove the default altogether?
+	 *
+	 */
+	mode?: CitationModeType;
+	/**
+	 * The string that prefaces a list of citation references.
+	 */
+	// richer than CSL 1.0, but matches biblatex/org-cite
+	prefix?: string;
+	/**
+	 * The string that follows a list of citation references.
+	 */
+	suffix?: string;
+	references: CiteRef[];
+};
+
+export type CiteRef = {
+	/**
+	 * A string that prefaces the citation reference.
+	 */
+	prefix?: string;
+	/**
+	 * The unique identifier token for the citation reference.
+	 */
+	refID: ID;
+	/**
+	 * A string that follows the citation reference.
+	 *
+	 * CSL styles recognize "locator" in citation references' suffix. For example, in the citation
+	 *
+	 *    [cite:see @Tarski-1965 chapter 1, for an example]
+	 *
+	 * "chapter 1" is the locator.  The whole citation is rendered as
+	 *
+	 *    (see Tarski 1965, chap. 1 for an example)
+	 *
+	 * in the default CSL style.
+	 *
+	 * The locator starts with a locator term listed in the LocatorTerms type.
+	 * The locator term is followed by a space and then the locator value.
+	 * The locator value is a string of numbers and/or letters.
+	 * The locator value may be discontinuous, in which case it is separated by commas. For example, "23, 25-36"
+	 * is a discontinuous locator value.
+	 *
+	 * The part of the suffix before the locator is appended to reference's prefix.
+	 * If no locator term is used, but a number is present, then "page" is assumed.
+	 *
+	 * Adapted from org-mode.
+	 *
+	 * See also https://pandoc.org/MANUAL.html#extension-citations
+	 */
+	// REVIEW: the above will fail in some cases, with pandoc syntax offering a fail safe of sorts.
+	// An alernative, more robust, approach is to use a structured array, as in the v1.1 branch.
+	suffix?: string;
+};

src/contributor.ts

@@ -1,41 +1,39 @@
+export abstract class Agent {
+	constructor(public name: string) {}
 
-
-// contributor modeling needs more thought in general
-
-export type Contributor = Person | Organization;
-
-export class Organization {
-  name: string;
-  location?: string;
-
-  constructor(name: string, location?: string) {
-    this.name = name;
-    this.location = location;
-  }
-
-  getSortName(): string {
-    return this.name;
-  }
+	getSortName(): string {
+		return `${this.name}`;
+	}
 }
 
-export class Person  {
-    familyName: string;
-    givenName: string;
+export class Person extends Agent {
+	givenName: string;
+	familyName: string;
+	constructor(name: string, gname: string, fname: string) {
+		super(name);
+		this.givenName = gname;
+		this.familyName = fname;
+	}
+
+	public override getSortName() {
+		return `${this.familyName}, ${this.givenName}`;
+	}
+}
 
-    constructor(givenName: string, familyName: string) {
-      this.givenName = givenName;
-      this.familyName = familyName;
-    }
+export class Organization extends Agent {}
 
-    getFullName(): string {
-      return `${this.givenName} ${this.familyName}`;
-    }
+const p1 = new Person("Jane Doe", "Jane", "Doe");
+const a1 = new Organization("United Nations");
 
-    getGivenInitial(): string {
-      return `${this.givenName[0]}`;
-    }
+function contributorKind(x: Person | Organization) {
+	// x is type Person or Organization here
+	if (x instanceof Person) {
+		// x is type Person here
+		x.familyName;
+	} else {
+		x.name;
+	}
+}
 
-    getSortName(): string {
-      return `${this.familyName}, ${this.givenName}`;
-    }
-  }
+contributorKind(p1);
+contributorKind(a1);