typings for rdf-ext/clownface (#41016)

* typings for rdf-ext/clownface

* refactor: separate interfaces which can be inferred by usage

* refactor: rename and redefined constructor params object

* refactor: remove lib/index.d.ts which does not match actual code

* fix: remove require import

* align add callback with reality

types/clownface/clownface-tests.ts

@@ -0,0 +1,145 @@
+import { Term, NamedNode, Dataset, Literal } from 'rdf-js';
+import Clownface = require('clownface/lib/Clownface');
+import clownface = require('clownface');
+
+const node: NamedNode = <any> {};
+const predicate: NamedNode = <any> {};
+const literal: Literal = <any> {};
+let term: Term = <any> {};
+
+// .ctor
+const dataset: Dataset = <any> {};
+const graph: NamedNode = <any> {};
+
+let cf = new Clownface({ dataset });
+cf = new Clownface({ dataset, graph });
+cf = new Clownface({ dataset, term });
+cf = new Clownface({ dataset, term: [term, term] });
+cf = new Clownface({ dataset, value: 'foo' });
+cf = new Clownface({ dataset, value: ['foo', 'bar'] });
+cf = new Clownface({ dataset, term: [term, term], value: ['foo', 'bar'] });
+
+// .addIn
+cf = cf.addIn(node);
+cf = cf.addIn(node, node);
+cf = cf.addIn([ node, node ], node);
+cf = cf.addIn(node, [ node, node ]);
+cf = cf.addIn([ node, node ], [ node, node ], child => {
+    const values: string[] = child.values;
+});
+cf = cf.addIn(node, child => {
+    cf = child;
+});
+cf = cf.addIn(cf.node(node), cf.node(node));
+
+// .addList
+cf = cf.addList(predicate, [node, node]);
+
+// .addOut
+cf = cf.addOut(predicate, node);
+cf = cf.addOut(predicate);
+cf = cf.addOut(predicate, ['', 0]);
+cf = cf.addOut([predicate, predicate], node);
+cf = cf.addOut(predicate, [node, node]);
+cf = cf.addOut([predicate, predicate], [node, node], child => {
+    const values: string[] = child.values;
+});
+cf = cf.addOut(predicate, child => {
+    const values: string[] = child.values;
+});
+cf = cf.addOut(cf.node(predicate), cf.node(node));
+
+// .blankNode
+let blankNode: Clownface;
+blankNode = cf.blankNode();
+blankNode = cf.blankNode('label');
+blankNode = cf.blankNode([ 'b1', 'b2' ]);
+
+// .deleteIn
+cf = cf.deleteIn();
+cf = cf.deleteIn(node);
+cf = cf.deleteIn([node, node]);
+
+// .deleteList
+cf = cf.deleteList(predicate);
+
+// .deleteOut
+cf = cf.deleteOut();
+cf = cf.deleteOut(node);
+cf = cf.deleteOut([node, node]);
+
+// factory
+cf = clownface({ dataset });
+cf = clownface({ dataset, term });
+cf = clownface({ dataset, graph });
+cf = clownface({ dataset, value: 'foo' });
+
+// .filter
+cf = cf.filter(() => true);
+cf = cf.filter((thus: Clownface) => true);
+
+// .forEach
+cf.forEach(() => {});
+cf.forEach((thus: Clownface) => {});
+
+// .has
+cf = cf.has(predicate, 'Stuart');
+cf = cf.has([predicate, predicate], 'Stuart');
+cf = cf.has(predicate, [literal, literal]);
+
+// .in
+cf = cf.in(node);
+cf = cf.in([node, node]);
+cf = cf.in(cf.node(node));
+
+// .list
+const iterator: Iterator<Term> = cf.list();
+
+// .literal
+cf = cf.literal('foo');
+cf = cf.literal(['foo', 'bar']);
+cf = cf.literal('foo', node);
+cf = cf.literal('foo', 'en');
+
+// .map
+const arr: Clownface[] = cf.map((item: Clownface) => item);
+const nums: number[] = cf.map((item: Clownface, index: number) => index);
+
+// .namedNode
+cf = cf.namedNode(node);
+cf = cf.namedNode('http://example.com/');
+cf = cf.namedNode(['http://example.com/', 'http://example.org/']);
+
+// .node
+cf = cf.node(node);
+cf = cf.node('foo');
+cf = cf.node(123);
+cf = cf.node(['foo', 'bar']);
+cf = cf.node('http://example.org/', { type: 'NamedNode' });
+cf = cf.node(null, { type: 'BlankNode' });
+cf = cf.node('example', { datatype: node.value });
+cf = cf.node('example', { datatype: node });
+
+// .out
+cf = cf.out(node);
+cf = cf.out([node, node]);
+cf = cf.out(cf.node([node, node]));
+
+// .term
+if (cf.term) {
+    term = cf.term;
+}
+
+// .terms
+const terms: Term[] = cf.terms;
+
+// .toArray
+const toArray: Clownface[] = cf.toArray();
+
+// .value
+if (cf.value) {
+    const valueProp: string = cf.value;
+}
+
+// .values
+const values: string[] = cf.values;

types/clownface/index.d.ts

@@ -0,0 +1,93 @@
+// Type definitions for clownface 0.12
+// Project: https://github.com/rdf-ext/clownface
+// Definitions by: tpluscode <https://github.com/tpluscode>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.3
+
+import { Term, DatasetCore, Quad_Graph, NamedNode, BlankNode, Literal } from 'rdf-js';
+
+declare namespace clownface {
+    type TermOrClownface = Clownface | Term;
+    type TermOrLiteral = TermOrClownface | string | number | boolean;
+
+    type AddCallback<D extends DatasetCore, X extends Term> = (added: SingleContextClownface<D, X>) => void;
+    type SingleOrArray<T> = T | T[];
+
+    type SingleOrArrayOfTerms = SingleOrArray<TermOrClownface>;
+    type SingleOrArrayOfTermsOrLiterals = SingleOrArray<TermOrLiteral>;
+
+    interface NodeOptions {
+        type?: 'BlankNode' | 'Literal' | 'NamedNode';
+        datatype?: Term | { toString(): string };
+        language?: string;
+    }
+
+    type ClownfaceInit<D extends DatasetCore = DatasetCore, T extends Term = Term>
+        = Partial<Pick<Clownface<D, T>, 'dataset' | '_context'> & { graph: Quad_Graph }>;
+
+    interface WithValue {
+        value: string | string[];
+    }
+
+    interface WithTerm {
+        term: Term | Term[];
+    }
+
+    interface Clownface<D extends DatasetCore = DatasetCore, T extends Term = Term> {
+        readonly term: T | undefined;
+        readonly terms: T[];
+        readonly value: string | undefined;
+        readonly values: string[];
+        readonly dataset: D;
+        readonly datasets: D[];
+        readonly _context: any;
+        list(): Iterator<Term>;
+        toArray(): Array<Clownface<D, T>>;
+        filter(cb: (quad: Clownface<D, T>) => boolean): Clownface<D, T>;
+        forEach(cb: (quad: Clownface<D, T>) => void): void;
+        map<X>(cb: (quad: Clownface<D, T>, index: number) => X): X[];
+
+        // tslint:disable:no-unnecessary-generics
+        node<X extends Term = Term>(values: SingleOrArray<boolean | string | number | Term | null>, options?: NodeOptions): SafeClownface<D, X>;
+        blankNode(values?: SingleOrArray<string>): SafeClownface<D, BlankNode>;
+        literal(values: SingleOrArray<boolean | string | number | Term | null>, languageOrDatatype?: string | NamedNode): SafeClownface<D, Literal>;
+        namedNode(values: SingleOrArray<string | NamedNode>): SafeClownface<D, NamedNode>;
+
+        in<X extends Term = Term>(predicates: SingleOrArrayOfTerms): SafeClownface<D, X>;
+        out<X extends Term = Term>(predicates: SingleOrArrayOfTerms): SafeClownface<D, X>;
+
+        has<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects?: SingleOrArrayOfTermsOrLiterals): SafeClownface<D, X>;
+
+        addIn<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objectsOrCallback?: SingleOrArrayOfTermsOrLiterals | AddCallback<D, X>): SafeClownface<D, X>;
+        addIn<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects: SingleOrArrayOfTermsOrLiterals, callback: AddCallback<D, X>): SafeClownface<D, X>;
+
+        addOut<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objectsOrCallback?: SingleOrArrayOfTermsOrLiterals | AddCallback<D, X>): SafeClownface<D, X>;
+        addOut<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects: SingleOrArrayOfTermsOrLiterals, callback: AddCallback<D, X>): SafeClownface<D, X>;
+
+        addList<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects?: SingleOrArrayOfTermsOrLiterals, callback?: AddCallback<D, X>): SafeClownface<D, X>;
+
+        deleteIn<X extends Term = Term>(predicates?: SingleOrArrayOfTerms): SafeClownface<D, X>;
+        deleteOut<X extends Term = Term>(predicates?: SingleOrArrayOfTerms): SafeClownface<D, X>;
+        deleteList<X extends Term = Term>(predicates: SingleOrArrayOfTerms): SafeClownface<D, X>;
+        // tslint:enable:no-unnecessary-generics
+    }
+
+    interface SafeClownface<D extends DatasetCore = DatasetCore, T extends Term = Term> extends Clownface<D, T> {
+        filter(cb: (quad: SingleContextClownface<D, T>) => boolean): SafeClownface<D, T>;
+        forEach(cb: (quad: SingleContextClownface<D, T>) => void): void;
+        map<X>(cb: (quad: SingleContextClownface<D, T>, index: number) => X): X[];
+        toArray(): Array<SingleContextClownface<D, T>>;
+    }
+
+    interface SingleContextClownface<D extends DatasetCore = DatasetCore, T extends Term = Term> extends SafeClownface<D, T> {
+        readonly term: T;
+        readonly terms: [T];
+        readonly value: string;
+        readonly values: [string];
+    }
+}
+
+declare function clownface<D extends DatasetCore>(options: clownface.ClownfaceInit<D> & clownface.WithTerm | clownface.ClownfaceInit<D> & clownface.WithValue): clownface.SafeClownface<D>;
+declare function clownface<D extends DatasetCore>(options: clownface.ClownfaceInit<D>): clownface.Clownface<D>;
+
+export = clownface;

types/clownface/lib/Clownface.d.ts

@@ -0,0 +1,55 @@
+import { BlankNode, DatasetCore, Literal, NamedNode, Quad_Graph, Term } from 'rdf-js';
+import {
+    Clownface as ClownfaceContract,
+    ClownfaceInit,
+    AddCallback,
+    NodeOptions,
+    SafeClownface,
+    SingleOrArray,
+    SingleOrArrayOfTerms,
+    SingleOrArrayOfTermsOrLiterals,
+    WithValue,
+    WithTerm
+} from '..';
+
+declare class Clownface<D extends DatasetCore = DatasetCore, T extends Term = Term> implements ClownfaceContract<D, T> {
+    constructor(options: ClownfaceInit & Partial<WithTerm> & Partial<WithValue>);
+    readonly term: T | undefined;
+    readonly terms: T[];
+    readonly value: string | undefined;
+    readonly values: string[];
+    readonly dataset: D;
+    readonly datasets: D[];
+    readonly _context: any;
+    list(): Iterator<Term>;
+    toArray(): Array<Clownface<D, T>>;
+    filter(cb: (quad: Clownface<D, T>) => boolean): Clownface<D, T>;
+    forEach(cb: (quad: Clownface<D, T>) => void): void;
+    map<X>(cb: (quad: Clownface<D, T>, index: number) => X): X[];
+
+    // tslint:disable:no-unnecessary-generics
+    node<X extends Term = Term>(values: SingleOrArray<boolean | string | number | Term | null>, options?: NodeOptions): SafeClownface<D, X>;
+    blankNode(values?: SingleOrArray<string>): SafeClownface<D, BlankNode>;
+    literal(values: SingleOrArray<boolean | string | number | Term | null>, languageOrDatatype?: string | NamedNode): SafeClownface<D, Literal>;
+    namedNode(values: SingleOrArray<string | NamedNode>): SafeClownface<D, NamedNode>;
+
+    in<X extends Term = Term>(predicates: SingleOrArrayOfTerms): SafeClownface<D, X>;
+    out<X extends Term = Term>(predicates: SingleOrArrayOfTerms): SafeClownface<D, X>;
+
+    has<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects?: SingleOrArrayOfTermsOrLiterals): SafeClownface<D, X>;
+
+    addIn<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objectsOrCallback?: SingleOrArrayOfTermsOrLiterals | AddCallback<D, X>): SafeClownface<D, X>;
+    addIn<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects: SingleOrArrayOfTermsOrLiterals, callback: AddCallback<D, X>): SafeClownface<D, X>;
+
+    addOut<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objectsOrCallback?: SingleOrArrayOfTermsOrLiterals | AddCallback<D, X>): SafeClownface<D, X>;
+    addOut<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects: SingleOrArrayOfTermsOrLiterals, callback: AddCallback<D, X>): SafeClownface<D, X>;
+
+    addList<X extends Term = Term>(predicates: SingleOrArrayOfTerms, objects?: SingleOrArrayOfTerms, callback?: AddCallback<D, X>): SafeClownface<D, X>;
+
+    deleteIn<X extends Term = Term>(predicates?: SingleOrArrayOfTerms): SafeClownface<D, X>;
+    deleteOut<X extends Term = Term>(predicates?: SingleOrArrayOfTerms): SafeClownface<D, X>;
+    deleteList<X extends Term = Term>(predicates: SingleOrArrayOfTerms): SafeClownface<D, X>;
+    // tslint:enable:no-unnecessary-generics
+}
+
+export = Clownface;

types/clownface/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictFunctionTypes": true,
+        "strictNullChecks": true,
+        "baseUrl": "../",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "clownface-tests.ts"
+    ]
+}

types/clownface/tslint.json

@@ -0,0 +1,3 @@
+{
+    "extends": "dtslint/dt.json"
+}