@lblod/mu-auth-sudo 1.0.0 → 1.1.0

package/README.md

@@ -42,6 +42,59 @@ await update(updateString, extraHeaders, connectionOptions);
 
 ```
 
+## Typescript usage
+
+The query method allows for specifying the resulting bindings you expect to receive. Additionally, there are special return types for
+ASK, CONSTRUCT and DESCRIBE queries.
+
+```ts
+
+const queryString = `SELECT * FROM { GRAPH ?g { ?s ?p ?o. } } LIMIT 1`;
+// for SELECT queries, list the variable bindings you ask for in the select as an array of strings
+const result = await querySudo<['g', 's', 'p', 'o']>(queryString);
+// result shape and bindings are now typed, and will fully autocomplete
+result.results.bindins[0].g.value
+
+const queryString = `ASK {?something ?exists "with this value"}`
+// for ASK queries, simply specify the literal 'ask' as the generic
+const result = await querySudo<'ask'>(queryString)
+// result shape is typed
+result.boolean
+
+const queryString = `DESCRIBE <http://my-cool.uri/1>`
+// for DESCRIBE queries, simply specify the literal 'describe' as the generic
+// note, this is fully equivalent to querySudo<['s', 'p', 'v']>
+const result = await querySudo<'describe'>(queryString)
+// result shape is typed
+result.results.bindings[0].s.value
+
+const queryString = `CONSTRUCT {?my ?triple ?pattern. } WHERE {?my ?triple ?pattern .}`
+// for CONSTRUCT queries, simply specify the literal 'construct' as the generic
+// note, this is fully equivalent to querySudo<['s', 'p', 'v']>
+const result = await querySudo<'construct'>(queryString)
+// result shape is typed
+result.results.bindings[0].s.value
+```
+
+If you don't care or don't know the result shape, you can simply leave out the generic. It defaults to `string[]`, which means 
+everything except the specific binding names will still be typed, e.g:
+
+```ts
+
+const queryString = `SELECT * FROM { GRAPH ?g { ?s ?p ?o. } } LIMIT 1`;
+const result = querySudo(queryString);
+
+// still fully typed
+const firstBinding = result.results.bindings[0]
+
+// won't complain, since we haven't specified the precise binding names
+const hmmm = firstBinding.banana
+
+// however, the shape of the binding is still typed
+const {value, type} = hmmm
+
+```
+
 ## Logging
 
 The verbosity of logging can be configured as in the [javascript template](https://github.com/mu-semtech/mu-javascript-template/blob/6ff43eaf51856783c6946e82344e31a3348ce4a3/README.md#logging) through following environment variables:

package/dist/auth-sudo.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="node" />
+export * from './sparql-result-types';
+import type { SPARQLQueryConfig, SPARQLResult } from './sparql-result-types';
 export interface ConnectionOptions {
     sparqlEndpoint?: string;
     authUser?: string;
@@ -6,22 +8,13 @@ export interface ConnectionOptions {
     authType?: "basic" | "digest";
     mayRetry?: boolean;
 }
-export interface SPARQLResult {
-    head: Record<string, any>;
-    results?: {
-        distinct: boolean;
-        ordered: boolean;
-        bindings: Record<string, any>[];
-    };
-    boolean?: boolean;
-}
 export declare class HTTPResponseError extends Error {
     httpStatus: number;
     httpStatusText: string;
     constructor(response: Response);
 }
-export declare function querySudo(queryString: string, extraHeaders?: Record<string, string>, connectionOptions?: ConnectionOptions): Promise<SPARQLResult | null>;
-export declare function updateSudo(queryString: string, extraHeaders?: Record<string, string>, connectionOptions?: ConnectionOptions): Promise<SPARQLResult | null>;
+export declare function querySudo<C extends SPARQLQueryConfig = string[]>(queryString: string, extraHeaders?: Record<string, string>, connectionOptions?: ConnectionOptions): Promise<SPARQLResult<C> | null>;
+export declare function updateSudo<C extends SPARQLQueryConfig = string[]>(queryString: string, extraHeaders?: Record<string, string>, connectionOptions?: ConnectionOptions): Promise<SPARQLResult<C> | null>;
 declare const defaultExport: {
     querySudo: typeof querySudo;
     updateSudo: typeof updateSudo;

package/dist/auth-sudo.js

@@ -1,4 +1,18 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -7,12 +21,16 @@ exports.updateSudo = exports.querySudo = exports.HTTPResponseError = void 0;
 const express_http_context_1 = __importDefault(require("express-http-context"));
 const env_var_1 = __importDefault(require("env-var"));
 const digest_fetch_1 = __importDefault(require("digest-fetch"));
-const SPARQL_ENDPOINT = env_var_1.default.get('MU_SPARQL_ENDPOINT').required().asString();
-const LOG_SPARQL_ALL = env_var_1.default.get('LOG_SPARQL_ALL').required().asString();
+__exportStar(require("./sparql-result-types"), exports);
+// The query methods accept an endpoint parameter in the connectionOptions, so we should not make this required for consumers
+// that want to explicitly pass the endpoint. Otherwise those consumers have to set this env var to a dummy value for no reason.
+// We check at runtime wether we have a suitable endpoint and error if not
+const SPARQL_ENDPOINT = env_var_1.default.get('MU_SPARQL_ENDPOINT').asString();
+const LOG_SPARQL_ALL = env_var_1.default.get('LOG_SPARQL_ALL').default('true').asString();
 const LOG_SPARQL_QUERIES = env_var_1.default.get('LOG_SPARQL_QUERIES').default(LOG_SPARQL_ALL).asBool();
 const LOG_SPARQL_UPDATES = env_var_1.default.get('LOG_SPARQL_UPDATES').default(LOG_SPARQL_ALL).asBool();
-const DEBUG_AUTH_HEADERS = env_var_1.default.get('DEBUG_AUTH_HEADERS').required().asBool();
-// The following configuration options are considered optional, but may be overriden as a temporary workaround for issues. Thus, a last resort.
+const DEBUG_AUTH_HEADERS = env_var_1.default.get('DEBUG_AUTH_HEADERS').default('false').asBool();
+// The following configuration options are optional and best left at the default values, but may be overriden as a temporary workaround for issues. Thus, a last resort.
 const RETRY = env_var_1.default.get('SUDO_QUERY_RETRY').default('false').asBool();
 const RETRY_MAX_ATTEMPTS = env_var_1.default.get('SUDO_QUERY_RETRY_MAX_ATTEMPTS').default('5').asInt();
 const RETRY_FOR_HTTP_STATUS_CODES = env_var_1.default.get('SUDO_QUERY_RETRY_FOR_HTTP_STATUS_CODES').default('').asArray();
@@ -28,6 +46,15 @@ class HTTPResponseError extends Error {
     }
 }
 exports.HTTPResponseError = HTTPResponseError;
+function ensureEndpoint(endpoint) {
+    if (typeof endpoint === "string") {
+        return endpoint;
+    }
+    if (typeof SPARQL_ENDPOINT === "string") {
+        return SPARQL_ENDPOINT;
+    }
+    throw new Error("No endpoint configured. Either pass it into the queryoptions, or make sure the MU_SPARQL_ENDPOINT environment variable is set.");
+}
 function defaultHeaders() {
     const headers = new Headers();
     headers.set('content-type', 'application/x-www-form-urlencoded');
@@ -40,7 +67,7 @@ function defaultHeaders() {
     return headers;
 }
 async function executeRawQuery(queryString, extraHeaders = {}, connectionOptions = {}, attempt = 0) {
-    const sparqlEndpoint = connectionOptions.sparqlEndpoint ?? SPARQL_ENDPOINT;
+    const sparqlEndpoint = ensureEndpoint(connectionOptions.sparqlEndpoint);
     const headers = defaultHeaders();
     for (const key of Object.keys(extraHeaders)) {
         headers.append(key, extraHeaders[key]);
@@ -100,7 +127,7 @@ async function executeRawQuery(queryString, extraHeaders = {}, connectionOptions
 }
 async function maybeJSON(response) {
     try {
-        return (await response.json());
+        return await response.json();
     }
     catch (e) {
         return null;

package/dist/sparql-result-types.d.ts

@@ -0,0 +1,34 @@
+export type Binding<B extends string[]> = {
+    [Key in B[number]]: {
+        type: string;
+        value: string;
+    };
+};
+export type SPARQLQueryResult<B extends string[]> = {
+    head: {
+        link: unknown[];
+        vars: B;
+    };
+    results: {
+        distinct: boolean;
+        ordered: boolean;
+        bindings: Binding<B>[];
+    };
+};
+export type SPARQLConstructResult = SPARQLQueryResult<['s', 'p', 'v']>;
+export type SPARQLDescribeResult = SPARQLQueryResult<['s', 'p', 'v']>;
+export type SPARQLAskResult = {
+    head: {
+        link: unknown[];
+    };
+    boolean: boolean;
+};
+type QueryTypes = 'ask' | 'construct' | 'describe';
+export interface ConfigMap {
+    'ask': SPARQLAskResult;
+    'construct': SPARQLConstructResult;
+    'describe': SPARQLDescribeResult;
+}
+export type SPARQLQueryConfig = QueryTypes | string[];
+export type SPARQLResult<C extends SPARQLQueryConfig> = C extends QueryTypes ? ConfigMap[C] : C extends string[] ? SPARQLQueryResult<C> : never;
+export {};

package/dist/sparql-result-types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lblod/mu-auth-sudo",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "this package provides an alternative sparql client for the mu-javascript-template that has sudo rights.",
   "main": "dist/auth-sudo.js",
   "types": "dist/auth-sudo.d.ts",