making API for javascripty

.eslintrc.json

@@ -32,6 +32,7 @@
     "functional/immutable-data": "off",
     "functional/prefer-immutable-types": "off",
     "functional/no-throw-statements": "off",
+    "functional/no-mixed-types": "off",
     "functional/functional-parameters": "off",
     "functional/prefer-type-literal": "off",
     "no-constant-condition": "off",

docs/docs/api.graph.mdx

@@ -1,8 +1,8 @@
 import Graph, { toc as GraphToc } from '../generated/classes/lib_graph.Graph.mdx';
-import Triple, { toc as TripleToc } from '../generated/types/lib_graph.Triple.mdx';
-import Instance, { toc as InstanceToc } from '../generated/types/lib_graph.Instance.mdx';
-import Edge, { toc as EdgeToc } from '../generated/types/lib_graph.Edge.mdx';
-import Attribute, { toc as AttributeToc } from '../generated/types/lib_graph.Attribute.mdx';
+import Triple, { toc as TripleToc } from '../generated/types/lib_types.Triple.mdx';
+import Instance, { toc as InstanceToc } from '../generated/types/lib_types.Instance.mdx';
+import Edge, { toc as EdgeToc } from '../generated/types/lib_types.Edge.mdx';
+import Attribute, { toc as AttributeToc } from '../generated/types/lib_types.Attribute.mdx';
 
 
 # graph

src/graph.ts

@@ -1 +1,2 @@
-export { Graph, Triple, Instance, Edge, Attribute } from './lib/graph';
+export { Graph } from './lib/graph';
+export { Triple, Instance, Edge, Attribute } from './lib/types';

src/index.ts

@@ -1,8 +1,9 @@
-export { parse, iterparse, parseTriples } from './lib/_parse';
-export { format, formatTriples } from './lib/_format';
+export { parse, iterparse, parseTriples } from './lib/parse';
+export { format, formatTriples } from './lib/format';
 export { interpret, configure } from './lib/layout';
 export { Tree } from './lib/tree';
-export { Graph, Triple } from './lib/graph';
+export { Graph } from './lib/graph';
+export { Triple, Instance, Edge, Attribute } from './lib/types';
 export {
   PENMANCodec,
   decode,

src/lib/_lexer.ts

@@ -120,6 +120,9 @@ export class TokenIterator {
       this._next = null;
     }
     this._last = current;
+    if (current == null) {
+      throw new Error('Unexpected end of input');
+    }
     return current;
   }
 
@@ -155,7 +158,7 @@ export class TokenIterator {
   }
 
   error(message: string, token?: Token): DecodeError {
-    let line: string | null = null;
+    let line: string | undefined;
     let lineno: number;
     let offset: number;
     if (token == null) {
@@ -226,7 +229,7 @@ const _lex = function* (
             `capturing group:\n${regex.source}`,
         );
       }
-      const token: Token = [typ, val, i, m.index, line];
+      const token: Token = [typ, val, i, m.index ?? 0, line];
       debug(`${token}`);
       yield token;
     }

src/lib/codec.ts

@@ -2,13 +2,13 @@
  * Serialization of PENMAN graphs.
  */
 
-import { format, formatTriples } from './_format';
-import { iterparse, parse, parseTriples } from './_parse';
+import { format, formatTriples } from './format';
 import { Graph } from './graph';
 import * as layout from './layout';
 import { Model } from './model';
+import { iterparse, parse, parseTriples } from './parse';
 import { Tree } from './tree';
-import { BasicTriple, Node, Variable } from './types';
+import { Node, Triple, Variable } from './types';
 
 // "Utility" types; not Penman-specific
 
@@ -18,11 +18,8 @@ import { BasicTriple, Node, Variable } from './types';
 export class PENMANCodec {
   model: Model;
 
-  constructor(model: Model | null = null) {
-    if (model === null) {
-      model = new Model();
-    }
-    this.model = model;
+  constructor(model?: Model) {
+    this.model = model ?? new Model();
   }
 
   /**
@@ -31,7 +28,7 @@ export class PENMANCodec {
    * @param s - A string containing a single PENMAN-serialized graph.
    * @returns The `Graph` object described by `s`.
    * @example
-   * import { PENMANCodec } from 'penman-js/codec';
+   * import { PENMANCodec } from 'penman-js';
    *
    * const codec = new PENMANCodec();
    * const graph = codec.decode('(b / bark-01 :ARG0 (d / dog))');
@@ -40,7 +37,7 @@ export class PENMANCodec {
    */
   decode(s: string): Graph {
     const tree = parse(s);
-    return layout.interpret(tree, this.model);
+    return layout.interpret(tree, { model: this.model });
   }
 
   /**
@@ -51,7 +48,7 @@ export class PENMANCodec {
    */
   *iterdecode(lines: string | string[]): IterableIterator<Graph> {
     for (const tree of iterparse(lines)) {
-      yield layout.interpret(tree, this.model);
+      yield layout.interpret(tree, { model: this.model });
     }
   }
 
@@ -78,7 +75,7 @@ export class PENMANCodec {
   /**
    * Parse a triple conjunction from *s*.
    */
-  parseTriples(s: string): BasicTriple[] {
+  parseTriples(s: string): Triple[] {
     return parseTriples(s);
   }
 
@@ -104,7 +101,7 @@ export class PENMANCodec {
     indent: number | null | undefined = -1,
     compact = false,
   ): string {
-    const tree = layout.configure(g, top, this.model);
+    const tree = layout.configure(g, { top, model: this.model });
     return this.format(tree, indent, compact);
   }
 
@@ -137,7 +134,7 @@ export class PENMANCodec {
    * // Expected output:
    * // 'instance(a, alpha) ^\\nARG0(a, b) ^\\ninstance(b, beta)'
    */
-  formatTriples(triples: BasicTriple[], indent = true): string {
+  formatTriples(triples: Triple[], indent = true): string {
     return formatTriples(triples, indent);
   }
 }

src/lib/constant.ts

@@ -83,7 +83,7 @@ export const type = (constant_string: string | null | undefined): Type => {
 export const evaluate = (
   constantString: string | null | undefined,
 ): Constant => {
-  let value: Constant = constantString;
+  let value: Constant = constantString ?? null;
   if (constantString == null || constantString === '') {
     value = null;
   } else {

src/lib/epigraph.ts

@@ -1,6 +1,6 @@
 /** Base classes for epigraphical markers. */
 
-import { BasicTriple } from './types';
+import { Triple } from './types';
 import { ArrayKeysMap } from './utils';
 
 export class Epidatum {
@@ -16,4 +16,4 @@ export class Epidatum {
 
 export type Epidata = Epidatum[];
 
-export class EpidataMap extends ArrayKeysMap<BasicTriple, Epidata> {}
+export class EpidataMap extends ArrayKeysMap<Triple, Epidata> {}

src/lib/exceptions.ts

@@ -27,25 +27,14 @@ export class LayoutError extends PenmanError {}
  * @noInheritDoc
  */
 export class DecodeError extends PenmanError {
-  message: string;
-  filename: string;
-  lineno: number;
-  offset: number;
-  text: string;
-
   constructor(
-    message: string = null,
-    filename: string = null,
-    lineno: number = null,
-    offset: number = null,
-    text: string = null,
+    message: string,
+    public filename?: string,
+    public lineno?: number,
+    public offset?: number,
+    public text?: string,
   ) {
     super(message);
-    this.message = message;
-    this.filename = filename;
-    this.lineno = lineno;
-    this.offset = offset;
-    this.text = text;
   }
 
   toString(): string {

src/lib/format.spec.ts

@@ -1,7 +1,7 @@
 import test from 'ava';
 
-import { format, formatTriples } from './_format';
-import { BasicTriple, Node } from './types';
+import { format, formatTriples } from './format';
+import { Node, Triple } from './types';
 
 test('format', (t) => {
   const input: Node = [
@@ -16,7 +16,7 @@ test('format', (t) => {
 });
 
 test('format_triples', (t) => {
-  const triples: BasicTriple[] = [
+  const triples: Triple[] = [
     ['b', 'instance', 'bark-01'],
     ['b', 'ARG0', 'd'],
     ['d', 'instance', 'dog'],

src/lib/_format.ts → src/lib/format.ts

@@ -1,5 +1,5 @@
 import { isAtomic, Tree } from './tree';
-import { BasicTriple, Branch, Node } from './types';
+import { Branch, Node, Triple } from './types';
 import { lstrip } from './utils';
 
 /**
@@ -51,10 +51,7 @@ export const format = (
  * // ARG0(b, d) ^
  * // instance(d, dog)
  */
-export const formatTriples = (
-  triples: BasicTriple[],
-  indent = true,
-): string => {
+export const formatTriples = (triples: Triple[], indent = true): string => {
   const delim = indent ? ' ^\n' : ' ^ ';
   // need to remove initial : on roles for triples
   const conjunction = triples.map(
@@ -76,7 +73,7 @@ const _formatNode = (
   if (!variable) {
     return '()'; // empty node
   }
-  if (!edges.length) {
+  if (!edges?.length) {
     return `(${variable})`; // var-only node
   }
   // determine appropriate joiner based on value of indent
@@ -118,7 +115,7 @@ const _formatNode = (
  */
 const _formatEdge = (
   edge: Branch,
-  indent: number | null,
+  indent: number | null | undefined,
   column: number,
   vars: Set<string>,
 ): string => {

src/lib/graph.ts

@@ -9,37 +9,19 @@ import isEqual from 'lodash.isequal';
 import { EpidataMap } from './epigraph';
 import { GraphError } from './exceptions';
 import type {
-  BasicTriple,
+  Attribute,
   Constant,
+  Edge,
+  Instance,
   Role,
-  Target,
+  Triple,
   Triples,
   Variable,
 } from './types';
 import { defaultdictPlusEqual } from './utils';
 
 export const CONCEPT_ROLE = ':instance';
 
-/**
- * Represents a relation between nodes or between a node and a constant.
- */
-export type Triple = [source: Variable, role: Role, target: Target];
-
-/**
- * A relation indicating the concept of a node.
- */
-export type Instance = [source: Variable, role: Role, target: Constant];
-
-/**
- * A relation between nodes.
- */
-export type Edge = [source: Variable, role: Role, target: Variable];
-
-/**
- * A relation between a node and a constant.
- */
-export type Attribute = [source: Variable, role: Role, target: Constant];
-
 // hacky way to get a unique id for each graph
 // since JS has no id() function like Python
 let graphIdCounter = 0;
@@ -77,7 +59,7 @@ export class Graph {
    */
   constructor(
     public triples: Triples = [],
-    top: Variable = null,
+    top: Variable | null = null,
     public epidata: EpidataMap = new EpidataMap(),
     public metadata: Record<string, string> = {},
   ) {
@@ -189,10 +171,10 @@ export class Graph {
       }
       const possible_sources = this.triples.map((t) => t[0]);
       const possible_targets = this.triples.map((t) => t[2]);
-      const possible_variables = new Set(
+      const possibleVariables = new Set(
         possible_targets.concat(possible_sources),
       );
-      if (!possible_variables.has(this._top)) {
+      if (!possibleVariables.has(this._top)) {
         this._top = null;
       }
       return this;
@@ -271,7 +253,7 @@ export class Graph {
     source: Variable | null = null,
     role: Role | null = null,
     target: Constant | null = null,
-  ): BasicTriple[] {
+  ): Triple[] {
     // TODO: check for undefined OR null
     if (source == null && role == null && target == null) {
       return this.triples.slice();