feat: add types package

.gitignore

@@ -132,6 +132,9 @@ packages/*
 # Temporary: allow web-app until new web-app integrated
 !packages/web-app
 
+# Allow types package
+!packages/types
+
 # .vscode generally
 .vscode/*
 

packages/types/__test__/skip.test.ts

@@ -0,0 +1,4 @@
+// No tests for typing (for now)
+describe("skip testing", () => {
+  test.skip('skip test', () => { })
+})

packages/types/package.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@biothings-explorer/types",
+  "version": "1.0.0",
+  "description": "A collection of common types used by Biothings Explorer",
+  "main": "./built/index.js",
+  "types": "./built/index.d.ts",
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc -b",
+    "clean": "rimraf ./built './**/tsconfig.tsbuildinfo'",
+    "build:clean": "pnpm run clean && pnpm run build",
+    "format": "prettier --check 'src/**/*.js'",
+    "format:fix": "prettier --write 'src/**/*.js'",
+    "lint": "eslint . --ext .js",
+    "lint:fix": "pnpm lint --fix",
+    "test": "jest",
+    "test-cov": "jest --coverage"
+  },
+  "keywords": [
+    "bte",
+    "biothings",
+    "single",
+    "hop",
+    "query"
+  ],
+  "author": "BioThings Team",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/biothings/biothings_explorer/issues"
+  },
+  "homepage": "https://github.com/biothings/biothings_explorer#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.12"
+  }
+}

packages/types/src/global.ts

@@ -0,0 +1,45 @@
+// Cursed globals that exist for Reasons
+
+import { TrapiQueryGraph } from "./trapi";
+import { SmartAPISpec } from "@biothings-explorer/smartapi-kg";
+import { Queue } from "bull";
+import Piscina from "piscina";
+
+export interface QueryQueue {
+  bte_sync_query_queue: Queue;
+  bte_query_queue: Queue;
+  bte_query_queue_by_api: Queue;
+  bte_query_queue_by_team: Queue;
+}
+
+export interface QueryInformation {
+  queryGraph: TrapiQueryGraph;
+  isCreativeMode?: boolean;
+  creativeTemplate?: string;
+  totalRecords?: number;
+  jobID?: string;
+  callback_url?: string;
+}
+
+export interface ThreadPool {
+  sync: Piscina;
+  async: Piscina;
+  misc: Piscina;
+}
+
+/* eslint no-var: off */
+declare global {
+  var missingAPIs: SmartAPISpec[];
+  var BIOLINK_VERSION: string;
+  var SCHEMA_VERSION: string;
+  var parentPort: MessagePort;
+  var cachingTasks: Promise<void>[];
+  var queryInformation: QueryInformation;
+  var job: {
+    log: (logString: string) => void;
+  }; // TODO type as Piscina job
+  var queryQueue: QueryQueue;
+  var threadpool: ThreadPool;
+}
+
+export { };

packages/types/src/index.ts

@@ -0,0 +1,4 @@
+import "./global";
+export * from "./trapi";
+export * from "./tasks";
+export * from "./misc";

packages/types/src/misc.ts

@@ -0,0 +1,13 @@
+export type APIDefinition = {
+  // Must have one of id or infores
+  id?: string; // SmartAPI ID, takes priority over infores
+  name: string; // Must match name on SmartAPI registry
+  infores?: string; // infores of API
+  primarySource?: boolean;
+} & ({ id: string } | { infores: string });
+
+export interface APIList {
+  include: APIDefinition[];
+  // takes priority over include, taking into account id/infores prioritization
+  exclude: APIDefinition[];
+}

packages/types/src/smartapi.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+
+export type paths = Record<string, never>;
+
+export type webhooks = Record<string, never>;
+
+export type components = Record<string, never>;
+
+export type $defs = Record<string, never>;
+
+export type external = Record<string, never>;
+
+export type operations = Record<string, never>;

packages/types/src/tasks.ts

@@ -0,0 +1,75 @@
+import { APIList } from "./misc";
+import { TrapiQueryGraph, TrapiResponse, TrapiWorkflow } from "./trapi";
+
+// Options as they are assembled from the route
+export interface QueryOptions {
+  logLevel?: string;
+  submitter?: string;
+  smartAPIID?: string;
+  teamName?: string;
+  dryrun?: boolean;
+  caching?: boolean; // from request url query values
+}
+
+// Options as they are passed to the Query Handler
+export interface QueryHandlerOptions extends QueryOptions {
+  provenanceUsesServiceProvider?: boolean;
+  enableIDResolution?: boolean;
+  apiList?: APIList;
+  schema?: unknown; // might be hard to type -- it's the entire TRAPI schema IIRC
+  resolveOutputIDs?: boolean;
+  EDGE_ATTRIBUTES_USED_IN_RECORD_HASH?: string[];
+}
+
+export interface QueueData {
+  queryGraph: TrapiQueryGraph;
+  options: QueryOptions;
+  workflow?: TrapiWorkflow[];
+  callback_url?: string;
+  smartAPIID?: string;
+  teamName?: string;
+}
+
+export interface QueryParams {
+  id: string | number; // Job ID
+}
+
+export interface TaskData extends QueueData {
+  route: string;
+  params?: QueryParams;
+  endpoint?: string;
+  abortController?: AbortController;
+  url?: string;
+  enableIDResolution?: boolean;
+}
+
+// Info provided to outer task function (defined alongside route)
+export interface TaskInfo {
+  id?: string | number;
+  data: TaskData;
+}
+
+// Info provided to task handler (inside thread)
+export interface InnerTaskData {
+  req: TaskInfo;
+  route: string;
+  port: MessagePort;
+  job?: {
+    jobId: string | number;
+    queueName: string;
+  };
+}
+
+// Data sent from thread to main to keep track of execution
+// TODO break down into types of messages
+export interface DialHome {
+  threadId: string | number;
+  cacheInProgress?: number;
+  addCacheKey?: string;
+  completeCacheKey?: string;
+  registerId?: string;
+  cacheDone?: number;
+  err?: Error;
+  result?: TrapiResponse;
+  status?: number;
+}

packages/types/src/trapi.ts

@@ -0,0 +1,186 @@
+export interface TrapiQNode {
+  ids?: string[];
+  categories?: string[];
+  is_set?: boolean;
+  constraints?: TrapiAttributeConstraint[];
+}
+
+export interface TrapiQEdge {
+  knowledge_type?: string;
+  predicates?: string[];
+  subject: string;
+  object: string;
+  attribute_constraints?: TrapiAttributeConstraint[];
+  qualifier_constraints?: TrapiQualifierConstraint[];
+}
+
+export interface TrapiQueryGraph {
+  nodes: {
+    [QNodeID: string]: TrapiQNode;
+  };
+  edges: {
+    [QEdgeID: string]: TrapiQEdge;
+  };
+}
+
+export interface TrapiSource {
+  resource_id: string;
+  resource_role: string;
+  upstream_resource_ids?: string[];
+}
+
+export interface TrapiKGNodes {
+  [nodeID: string]: TrapiKGNode;
+}
+
+export interface TrapiKGEdges {
+  [edgeID: string]: TrapiKGEdge;
+}
+
+export interface TrapiKnowledgeGraph {
+  nodes: TrapiKGNodes;
+  edges: TrapiKGEdges;
+}
+
+export interface TrapiKGEdge {
+  predicate: string;
+  subject: string;
+  object: string;
+  attributes?: TrapiAttribute[];
+  qualifiers?: TrapiQualifier[];
+  sources: TrapiSource[];
+}
+
+export interface TrapiKGNode {
+  categories: string[];
+  name: string;
+  attributes?: TrapiAttribute[];
+}
+
+export interface TrapiAttribute {
+  attribute_type_id: string;
+  original_attribute_name?: string;
+  value: string | string[] | number | number[];
+  value_type_id?: string;
+  attribute_source?: string | null;
+  value_url?: string | null;
+  attributes?: TrapiAttribute;
+  [additionalProperties: string]:
+  | string
+  | string[]
+  | null
+  | TrapiAttribute
+  | number
+  | number[];
+}
+
+export interface TrapiQualifier {
+  qualifier_type_id: string;
+  qualifier_value: string | string[];
+}
+
+export interface TrapiQualifierConstraint {
+  qualifier_set: TrapiQualifier[];
+}
+
+export interface TrapiAttributeConstraint {
+  id: string;
+  name: string;
+  not: boolean;
+  operator: string;
+  value: string | string[] | number | number[];
+}
+
+export interface TrapiNodeBinding {
+  id: string;
+  query_id?: string;
+  attributes?: TrapiAttribute[];
+}
+
+export interface TrapiEdgeBinding {
+  id: string;
+  attributes?: TrapiAttribute[];
+}
+
+export interface TrapiAnalysis {
+  resource_id?: string;
+  score?: number;
+  edge_bindings: {
+    [qEdgeID: string]: TrapiEdgeBinding[];
+  };
+  support_graphs?: string[];
+  scoring_method?: string;
+  attributes?: TrapiAttribute[];
+}
+
+export interface TrapiAuxiliaryGraph {
+  edges: string[];
+  attributes?: TrapiAttribute[];
+}
+
+export interface TrapiPfocrFigure {
+  figureUrl: string;
+  pmc: string;
+  matchedCuries: string[];
+  score: number;
+}
+
+export interface TrapiResult {
+  node_bindings: {
+    [qNodeID: string]: TrapiNodeBinding[];
+  };
+  analyses: TrapiAnalysis[];
+  pfocr?: TrapiPfocrFigure[];
+}
+
+export interface TrapiAuxGraphCollection {
+  [supportGraphID: string]: TrapiAuxiliaryGraph;
+}
+
+export interface TrapiLog {
+  timestamp: string;
+  level: string;
+  message: string;
+  code: string;
+}
+
+export interface TrapiWorkflow {
+  id: string;
+}
+
+export interface TrapiQueryMessage {
+  query_graph: TrapiQueryGraph;
+}
+
+export interface TrapiResponseMessage {
+  query_graph: TrapiQueryGraph;
+  knowledge_graph: TrapiKnowledgeGraph;
+  auxiliary_graphs?: TrapiAuxGraphCollection;
+  results: TrapiResult[];
+}
+
+export interface TrapiQuery {
+  message: TrapiQueryMessage;
+  log_level?: string;
+  workflow?: TrapiWorkflow[];
+  submitter?: string;
+  callback?: string;
+}
+
+export interface TrapiResponse {
+  status?: string;
+  description?: string;
+  schema_version?: string;
+  biolink_version?: string;
+  workflow?: TrapiWorkflow[];
+  message: TrapiResponseMessage;
+  logs: TrapiLog[];
+  trace?: string; // Only used in dev
+}
+
+export interface TrapiAsyncStatusResponse {
+  status: string;
+  description: string;
+  logs: TrapiLog[];
+  response_url?: string;
+}