feat(types): add type definitions

index.d.ts

@@ -0,0 +1,81 @@
+// JsonML
+// see: http://www.jsonml.org/syntax/
+//
+// `Node` type imported from lib.dom
+//
+/// <reference lib="dom"/>
+
+export type AttributeValue = any;
+
+export interface Attributes {
+  [key: string]: AttributeValue;
+}
+
+type TagName = string;
+
+type TextNode = string;
+
+export type JSONMLElement = [ TagName ]
+  | [ TagName, Attributes ]
+  | [ TagName, ...JSONMLNode[] ]
+  | [ TagName, Attributes, ...JSONMLNode[] ]
+  ;
+
+export type JSONMLNode = JSONMLElement | TextNode
+
+
+// Utils
+export function isFragment(jml: JSONMLElement): boolean;
+
+export function isMarkup(value: any): boolean;
+
+export function getTagName(jml: JSONMLElement): TagName;
+
+export function isElement(value: any): boolean;
+
+export function isAttributes(value: any): boolean;
+
+export function hasAttributes(jml: JSONMLElement): boolean;
+
+export function getAttributes(jml: JSONMLElement, addIfMissing?: boolean): Attributes;
+
+export function addAttributes(jml: JSONMLElement, attr: Attributes): void;
+
+export function getAttribute(jml: JSONMLElement, key: string): AttributeValue | void;
+
+export function setAttribute(jml: JSONMLElement, key: string, value: AttributeValue): void;
+
+export function appendChild(jml: JSONMLElement, child: JSONMLElement): boolean;
+
+export function getChildren(jml: JSONMLElement): JSONMLNode[];
+
+
+// DOM
+export type JSONMLElementFilter = (jml: JSONMLElement, elem: JSONMLNode) => JSONMLElement | null;
+
+export function fromHTML(elem: Node, filter?: JSONMLElementFilter): JSONMLElement | null;
+
+export function fromHTMLText(html: string, filter?: JSONMLElementFilter): JSONMLElement | null;
+
+
+// HTML
+export class Markup {
+  value: string
+  toString(): string
+}
+
+export type HTMLElementFilter = (elem: Node) => Node
+
+export type ErrorHandler = (err: Error, jml: JSONMLElement, filter?: HTMLElementFilter) => any
+
+export function raw(value: string): Markup;
+
+export function isRaw(value: any): boolean;
+
+export let onerror: null | ErrorHandler
+
+export function patch(elem: Node, jml: JSONMLElement, filter?: HTMLElementFilter): Node
+
+export function toHTML(jml: string | JSONMLElement, filter?: HTMLElementFilter): Node
+
+export function toHTMLText(jml: string | JSONMLElement, filter?: HTMLElementFilter): string

package.json

@@ -3,10 +3,12 @@
   "version": "2.1.0",
   "description": "JsonML-related tools.",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "*.md",
     "dist",
-    "index.js"
+    "index.js",
+    "index.d.ts"
   ],
   "scripts": {
     "lint": "eslint ./lib/utils.js ./test",
@@ -15,7 +17,9 @@
     "build": "babel lib --out-dir dist",
     "prepublishOnly": "babel lib --out-dir dist",
     "pretest": "npm run lint",
-    "test": "nyc mocha"
+    "test": "nyc mocha",
+    "test:types": "tsc --noEmit test/types.test.ts",
+    "posttest": "npm run test:types"
   },
   "keywords": [
     "jsonml",
@@ -55,6 +59,7 @@
     "eslint": "^6.0.0",
     "eslint-config-egg": "^8.0.0",
     "mocha": "^7.0.0",
-    "nyc": "^15.0.0"
+    "nyc": "^15.0.0",
+    "typescript": "^3.8.2"
   }
 }

test/types.test.ts

@@ -0,0 +1,51 @@
+import {
+  Attributes,
+  AttributeValue,
+  JSONMLNode,
+} from '..';
+
+import * as jsonml from '..';
+
+// Utils
+const isFragYes: boolean = jsonml.isFragment(['', 'hi']);
+const isFragNo: boolean = jsonml.isFragment(['div', 'hi']);
+
+const isMarkupYes: boolean = jsonml.isMarkup(jsonml.raw('hello'));
+const isMarkupNo: boolean = jsonml.isMarkup(['div', 'hello']);
+
+const paraTag: string = jsonml.getTagName(['p', 'some text']);
+const fragTag: string = jsonml.getTagName(['', 'some fragment text']);
+
+const foo = jsonml.getTagName([
+  '', // fragment
+  { foo: 'bar' }, // attributes allowed here
+  ['p', { foo: 'bar' }, 'some fragment text'],
+  ['p', { foo: 'bar' }, 'some fragment text'],
+  ['div', 'foo'],
+  'baz'
+]);
+
+const isElemYes: boolean = jsonml.isElement(['img', { href: 'https://example.com/foo.jpg' }]);
+const isElemNo: boolean = jsonml.isElement({});
+
+const isAttrsYes: boolean = jsonml.isAttributes({ foo: 'bar' });
+const isAttrsNo: boolean = jsonml.isAttributes(['foo']);
+
+const hasAttrsYes: boolean = jsonml.hasAttributes(['p', { foo: 'bar' }]);
+const hasAttrsNo: boolean = jsonml.hasAttributes(['p']);
+
+const gotAttrs: Attributes = jsonml.getAttributes(['p', { foo: 'bar' }]);
+const gotAddedAttrs: Attributes = jsonml.getAttributes(['p'], true);
+const gotEmptyAttrs: Attributes = jsonml.getAttributes(['p'], false);
+
+const addAttributesRetval: void = jsonml.addAttributes(['p'], { foo: 'bar', a: 1 });
+
+type MaybeAttributeValue = AttributeValue | void;
+const gotAttr: MaybeAttributeValue = jsonml.getAttribute(['p', { foo: 'bar' }], 'foo');
+const gotNoAttr: MaybeAttributeValue = jsonml.getAttribute(['p', { foo: 'bar' }], 'this-does-not-exist');
+
+const setAttributeRetval: void = jsonml.setAttribute(['p'], 'foo', 'bar');
+
+const childWasAppended: boolean = jsonml.appendChild(['p', { foo: 'bar'}], ['strong', 'Hello World', ['em', 'another'], 'bye' ]);
+
+const gotChildren: JSONMLNode[] = jsonml.getChildren(['div', ['p', 'one'], ['p', 'two'], 'foo']);

tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "noEmit": true,
+    "strict": true,
+    "target": "es6",
+    "lib": [
+      "es2015",
+      "dom"
+    ]
+  }
+}