feat(types): add TypeScript types

.gitignore

@@ -1,2 +1,3 @@
 node_modules
 scripts/sitelinks_languages/sites.json
+types/**/*.js

package.json

@@ -5,15 +5,18 @@
   "main": "lib/index.js",
   "files": [
     "dist",
-    "lib"
+    "lib",
+    "types/**/*.d.ts"
   ],
+  "types": "types/index.d.ts",
   "directories": {
     "lib": "lib",
     "doc": "docs",
     "test": "test"
   },
   "scripts": {
     "test": "mocha",
+    "test-types": "tsc",
     "test-watch": "mocha --watch",
     "lint": "standard",
     "build": "browserify lib/index.js -s wdk -o dist/wikidata-sdk.js -t [ babelify --presets [ es2015 ] ]",
@@ -60,6 +63,7 @@
     "mocha": "^5.1.1",
     "should": "^13.2.1",
     "standard": "^10.0.3",
+    "typescript": "^3.3.4000",
     "uglify-js": "^3.3.25",
     "wikidata-cli": "^6.0.8"
   },

tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "compilerOptions": {
+        "target": "es2016",
+        "module": "commonjs",
+        "moduleResolution": "node",
+        "forceConsistentCasingInFileNames": true,
+        "strict": true
+    },
+    "include": [
+      "types"
+    ]
+}

types/claim.d.ts

@@ -0,0 +1,56 @@
+import {Dictionary} from './helper'
+
+export type ClaimRank = 'normal' | 'preferred' | 'deprecated'
+
+export type ClaimSimplified = unknown;
+export type ClaimSnakSimplified = unknown;
+
+export interface Claim {
+	id: string;
+	mainsnak: ClaimSnak;
+	rank: ClaimRank;
+	type: string;
+	qualifiers?: Dictionary<ClaimSnak[]>;
+	'qualifiers-order'?: string[];
+	references?: ClaimReference[];
+}
+
+export interface ClaimSnak {
+	datatype: string;
+	datavalue?: ClaimSnakValue;
+	hash: string;
+	property: string;
+	snaktype: string;
+}
+
+export interface ClaimSnakValue {
+	type: string;
+	value: unknown;
+}
+
+export interface ClaimSnakTimeValue extends ClaimSnakValue {
+	type: 'time';
+	value: {
+		after: number;
+		before: number;
+		calendermodel: string;
+		precision: number;
+		time: string;
+		timezone: number;
+	};
+}
+
+export interface ClaimSnakEntityValue extends ClaimSnakValue {
+	type: 'wikibase-entityid';
+	value: {
+		id: string;
+		'numeric-id': number;
+		'entity-type': string;
+	};
+}
+
+export interface ClaimReference {
+	hash: string;
+	snaks: Dictionary<ClaimSnak[]>;
+	'snaks-order': string[];
+}

types/entity.d.ts

@@ -0,0 +1,48 @@
+import {Claim, ClaimSimplified} from './claim.d'
+import {Dictionary} from './helper'
+
+export interface LanguageEntry {
+	language: string;
+	value: string;
+}
+
+export interface Entity {
+	type: string;
+	datatype?: string;
+	id: string;
+
+	// Info
+	pageid?: number;
+	ns?: number;
+	title?: string;
+	lastrevid?: number;
+	modified?: string;
+
+	// Available when asked for in GetEntitiesOptions
+	aliases?: Dictionary<LanguageEntry[]>;
+	claims?: Dictionary<Claim[]>;
+	descriptions?: Dictionary<LanguageEntry>;
+	labels?: Dictionary<LanguageEntry>;
+	sitelinks?: Dictionary<Sitelink>;
+}
+
+export interface EntitySimplified {
+	type: string;
+	id: string;
+
+	// Info
+	modified?: string;
+
+	aliases?: Dictionary<string[]>;
+	claims?: Dictionary<ClaimSimplified[]>;
+	descriptions?: Dictionary<string>;
+	labels?: Dictionary<string>;
+	sitelinks?: {[site: string]: string};
+}
+
+export interface Sitelink {
+	site: string;
+	title: string;
+	badges: string[];
+	url?: string;
+}

types/helper.d.ts

@@ -0,0 +1,3 @@
+export interface Dictionary<T> {
+	[key: string]: T;
+}

types/index.d.ts

@@ -0,0 +1,107 @@
+import {
+	Property,
+	SearchType,
+	UrlResultFormat,
+	GetEntitiesFromSitelinksOptions,
+	GetEntitiesOptions,
+	GetReverseClaimOptions,
+	GetRevisionsOptions,
+	SearchEntitiesOptions,
+	SimplifyClaimsOptions,
+	SimplifyEntitiesOptions,
+	SimplifySitelinkOptions
+} from './options.d'
+
+import {
+	Claim,
+	ClaimSimplified,
+	ClaimSnak,
+	ClaimSnakSimplified
+} from './claim.d'
+
+import {
+	Entity,
+	EntitySimplified,
+	LanguageEntry,
+	Sitelink
+} from './entity.d'
+
+import {
+	SparqlValueRaw,
+	SparqlValueType,
+	SparqlResults
+} from './sparql.d'
+
+import {Dictionary} from './helper'
+
+export as namespace wdk
+
+export * from './claim.d'
+export * from './entity.d'
+export * from './options.d'
+export * from './search.d'
+export * from './sparql.d'
+
+export function searchEntities(search: string, language?: string, limit?: number, format?: UrlResultFormat, uselang?: string): string;
+export function searchEntities(options: SearchEntitiesOptions): string;
+
+export function getEntities(ids: string | string[], languages?: string | string[], props?: Property | Property[], format?: UrlResultFormat): string;
+export function getEntities(options: GetEntitiesOptions): string;
+
+export function getManyEntities(ids: string | string[], languages?: string | string[], props?: Property | Property[], format?: UrlResultFormat): string[];
+export function getManyEntities(options: GetEntitiesOptions): string[];
+
+export function sparqlQuery(query: string): string;
+
+export function getReverseClaims(property: string | string[], value: string | string[], options?: GetReverseClaimOptions): string;
+
+export function getRevisions(ids: string | string[], options?: GetRevisionsOptions): string;
+
+export function getEntitiesFromSitelinks(titles: string | string[], sites: string | string[], languages?: string | string[], props?: string | string[], format?: UrlResultFormat): string;
+export function getEntitiesFromSitelinks(options: GetEntitiesFromSitelinksOptions): string;
+
+// Helpers
+export function isNumericId(id: string): boolean;
+export function isEntityId(id: string): boolean;
+export function isItemId(id: string): boolean;
+export function isPropertyId(id: string): boolean;
+export function isGuid(guid: string): boolean;
+
+export function getNumericId(id: string): number;
+
+export function truthyClaims(claims: Dictionary<Claim[]>): Dictionary<Claim[]>;
+export function truthyPropertyClaims(claims: Claim[]): Claim[];
+
+export function wikidataTimeToDateObject(wikidataTime: string): Date;
+export function wikidataTimeToEpochTime(wikidataTime: string): number;
+export function wikidataTimeToISOString(wikidataTime: string): string;
+export function wikidataTimeToSimpleDay(wikidataTime: string): string;
+
+export function getImageUrl(filename: string, width?: number): string;
+
+// Sitelink helpers
+export function getSitelinkUrl(site: string, title: string): string;
+export function getSitelinkData(site: string): {lang: string; project: string};
+export function isSitelinkKey(site: string): boolean;
+
+export namespace simplify {
+	export function labels(data: Dictionary<LanguageEntry>): Dictionary<string>;
+	export function descriptions(data: Dictionary<LanguageEntry>): Dictionary<string>;
+	export function aliases(data: Dictionary<LanguageEntry[]>): Dictionary<string[]>;
+
+	export function entity(entity: Entity, options?: SimplifyEntitiesOptions): EntitySimplified;
+	export function entities(entities: Dictionary<Entity>, options?: SimplifyEntitiesOptions): Dictionary<EntitySimplified>;
+	export function sparqlResults(results: SparqlResults, options?: {minimize?: false}): Dictionary<SparqlValueType>[];
+	export function sparqlResults(results: SparqlResults, options: {minimize: true}): SparqlValueRaw[];
+
+	export function claims(claims: Dictionary<Claim[]>, options?: SimplifyClaimsOptions): Dictionary<ClaimSimplified[]>;
+	export function propertyClaims(propClaims: Claim[], options?: SimplifyClaimsOptions): ClaimSimplified[];
+	export function claim(claim: Claim, options?: SimplifyClaimsOptions): ClaimSimplified;
+
+	export function qualifiers(qualifiers: Dictionary<ClaimSnak[]>, options?: SimplifyClaimsOptions): Dictionary<ClaimSnakSimplified[]>;
+	export function propertyQualifiers(propQualifiers: ClaimSnak[], options?: SimplifyClaimsOptions): ClaimSnakSimplified[];
+	export function qualifier(qualifier: ClaimSnak, options?: SimplifyClaimsOptions): ClaimSnakSimplified;
+
+	export function sitelinks(sitelinks: Dictionary<Sitelink>, options?: {addUrl?: false} & SimplifySitelinkOptions): Dictionary<string>;
+	export function sitelinks(sitelinks: Dictionary<Sitelink>, options?: {addUrl: true} & SimplifySitelinkOptions): Dictionary<{title: string, url: string}>;
+}

types/options.d.ts

@@ -0,0 +1,60 @@
+export type Property = 'info' | 'sitelinks' | 'sitelinks/urls' | 'aliases' | 'labels' | 'descriptions' | 'claims' | 'datatype';
+export type SearchType = 'item' | 'property' | 'lexeme' | 'form' | 'sense'
+export type UrlResultFormat = 'xml' | 'json';
+
+export interface GetEntitiesFromSitelinksOptions {
+	titles: string | string[];
+	sites: string | string[];
+	languages?: string | string[];
+	props?: string | string[];
+	format?: UrlResultFormat;
+}
+
+export interface GetEntitiesOptions {
+	ids: string | string[];
+	languages?: string | string[];
+	props?: Property | Property[];
+	format?: UrlResultFormat;
+}
+
+export interface GetReverseClaimOptions {
+	limit?: number;
+	keepProperties?: boolean;
+	caseInsensitive?: boolean;
+}
+
+export interface GetRevisionsOptions {
+	limit?: number;
+	start?: string | number;
+	end?: string | number;
+}
+
+export interface SearchEntitiesOptions {
+	search: string;
+	language?: string;
+	limit?: number;
+	format?: UrlResultFormat;
+	uselang?: string;
+	type?: SearchType;
+}
+
+export interface SimplifyClaimsOptions {
+	entityPrefix?: string;
+	propertyPrefix?: string;
+	keepRichValues?: boolean;
+	keepTypes?: boolean;
+	keepQualifiers?: boolean;
+	keepReferences?: boolean;
+	keepIds?: boolean;
+	keepHashes?: boolean;
+	keepNonTruthy?: boolean;
+	timeConverter?: 'iso' | 'epoch' | 'simple-day' | 'none';
+	novalueValue: any;
+	somevalueValue: any;
+}
+
+export interface SimplifyEntitiesOptions extends SimplifyClaimsOptions, SimplifySitelinkOptions {}
+
+export interface SimplifySitelinkOptions {
+	addUrl?: boolean;
+}

types/search.d.ts

@@ -0,0 +1,16 @@
+export interface SearchResult {
+	aliases?: string[]
+	concepturi: string;
+	description?: string;
+	id: string;
+	label: string;
+	match: {
+		language: string;
+		text: string;
+		type: string;
+	};
+	pageid: number;
+	repository: string;
+	title: string;
+	url: string;
+}

types/sparql.d.ts

@@ -0,0 +1,13 @@
+import {Dictionary} from './helper'
+
+export type SparqlValueRaw = string | number
+export type SparqlValueType = SparqlValueRaw | Dictionary<SparqlValueRaw>
+
+export interface SparqlResults {
+	head: {
+		vars: string[];
+	};
+	results: {
+		bindings: any[];
+	};
+}

types/test/README.md

@@ -0,0 +1,5 @@
+# Check Typescript Types
+
+These files do not have to "work". They have to compile with typescript typing.
+
+Use: `npm run test-types`