startgg-helper 1.0.2

package/main.js

@@ -0,0 +1,2 @@
+export * from "./src/query.js"
+export * from "./src/queryLimiter.js"

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "startgg-helper",
+  "version": "1.0.2",
+  "description": "A set of functions and classes useful to communicate with the start.gg API, using any client (YOU NEED TO PROVIDE A CLIENT YOURSELF, SEE README)",
+  "main": "main.js",
+  "scripts": {
+    "test": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js --silent"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/TwilCynder/startgg-helper.git"
+  },
+  "keywords": [
+    "start.gg",
+    "API",
+    "GraphQL"
+  ],
+  "author": "TwilCynder",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://gitlab.com/TwilCynder/startgg-helper/issues"
+  },
+  "homepage": "https://gitlab.com/TwilCynder/startgg-helper#readme",
+  "devDependencies": {
+    "@twilcynder/arguments-parser": "^1.16.1",
+    "@types/jest": "^29.5.12",
+    "graphql-request": "^7.1.0",
+    "jest": "^29.7.0"
+  },
+  "type": "module",
+  "jest": {
+    "transform": {}
+  }
+}

package/readme.md

@@ -0,0 +1,16 @@
+# start.gg Helper
+
+A set of functions and classes useful to interact with the start.gg GraphQL API.  
+
+## You need to provide a client to interact with the API
+The functions in this package usually take a "client" argument, which is a GraphQL client object. You need to handle this object yourself, which can be done using the `graphql` package, which is not a dependency of `startgg-helper` and must be installed manually.
+
+### Why do this ?
+
+The purpose of this package is to be usable not onlyin a node ecosystem but also in a browser project, using `browserify`. The `graphql` package does not work well with browserify, so I decided to let the user provide a client depending on their environment.
+
+### Ok actually you can just use startgg-helper-node or startgg-helper-browser
+
+If you don't want to handle the client yourself, you can simply install
+- `startgg-helper-node` if you're on Node, it includes `graphql` and handles the client using this package
+- `startgg-helper-browser` if you're doing a browser-based app using `browserify`, which provides a custom client class based on the `fetch` API.

package/src/jsUtil.js

@@ -0,0 +1,25 @@
+/**
+ * 
+ * @param {{}} obj 
+ * @param {string} path 
+ * @param {*} def 
+ * @returns 
+ */
+export function deep_get(obj, path, def = null){
+    //https://stackoverflow.com/a/8817473
+    path = path=path.split('.');
+    for (let i = 0; i < path.length; i++){
+        if (/^\d/.test(path[i])){
+            let n = parseInt(path[i]);
+            if (!isNaN){
+                path[i] = n;
+            }
+        }
+    }
+
+    for (var i=0, len=path.length; i<len; i++){
+        obj = obj[path[i]];
+        if (obj == undefined) return def;
+    };
+    return obj;
+};

package/src/query.js

@@ -0,0 +1,133 @@
+import { deep_get } from './jsUtil.js';
+import { TimedQuerySemaphore } from './queryLimiter.js'
+
+/**
+ * Dummy client class that's only used in the JSDoc. 
+ * In a real use case, the user will have their own client class.
+ */
+export class Client {
+    request(){}
+}
+
+export class Query {
+    #schema;
+    #maxTries;
+
+    /**
+     * 
+     * @param {string} schema 
+     * @param {number?} maxTries 
+     */
+    constructor (schema, maxTries = null){
+        this.#schema = schema;
+        this.#maxTries = maxTries;
+    }
+
+    /**
+     * 
+     * @param {string} logName 
+     * @param {{[varName: string]: value}} params 
+     * @returns 
+     */
+    #getLog(logName, params){
+        if (!this.log) return null;
+        let log = this.log[logName];
+        if (log){
+            if (typeof log == "string"){
+                return log;
+            } else if (typeof log == "function"){
+                return log(params);
+            }
+        }
+        return null;
+    }
+
+    /**
+     * 
+     * @param {Client} client 
+     * @param {{[varName: string]: value}} params 
+     * @param {number} tries How many tries in are we 
+     * @param {TimedQuerySemaphore} limiter 
+     * @param {boolean} silentErrors 
+     * @param {number} maxTries Overrides this.#maxTries
+     * @returns 
+     */
+    async #execute_(client, params, tries, limiter = null, silentErrors = false, maxTries = null){
+        maxTries = maxTries || this.#maxTries || 1
+
+        console.log((this.#getLog("query", params) || "Querying ...") + " Try " + (tries + 1));
+        try {
+            let data = await ( limiter ? limiter.execute(client, this.#schema, params) : client.request(this.#schema, params));
+            
+            return data;
+        } catch (e) {
+            
+            if (tries >= maxTries) {
+                console.error("Maximum number of tries reached. Throwing.", e);
+                throw e;
+            }
+            console.error((this.#getLog("error", params) || "Request failed.") + ` Retrying (try ${tries + 1}). Error : `, e);
+            return this.#execute_(client, params, tries + 1, limiter, silentErrors, maxTries);
+        }
+    }
+
+    /**
+     * Executes the query with given parameters and client
+     * @param {Client} client 
+     * @param {{[varName: string]: value}} params 
+     * @param {TimedQuerySemaphore} limiter 
+     * @param {boolean} silentErrors 
+     * @param {number} maxTries Overrides the default maximum tries count for this query
+     * @returns 
+     */
+    async execute(client, params, limiter = null, silentErrors = false, maxTries = null){
+        return await this.#execute_(client, params, 0, limiter, silentErrors, maxTries);
+    }
+
+    /**
+     * Executes a query containing a paginated collection, repeatedly, increasing the page index each time until nothing is returned, returning an aggregation of all the pages.
+     * @param {Client} client 
+     * @param {{[varName: string]: value}} params 
+     * @param {string} collectionPathInQuery JSON path to the paginated collection that must aggregated in the query (JSON path : property names separated by dots)
+     * @param {TimedQuerySemaphore} limiter 
+     * @param {number} delay Adds a delay between calls (does not interact with the limiter)
+     * @param {string} pageParamName Name of the query parameter that must be updated with a page index for each query
+     * @param {boolean} silentErrors 
+     * @param {number} maxTries 
+     * @returns 
+     */
+    async executePaginated(client, params, collectionPathInQuery, limiter = null, delay = null, perPage = undefined, pageParamName = "page", perPageParamName = "perPage", silentErrors = false, maxTries = null){
+        let result = [];
+
+
+        params = Object.assign({}, params);
+        params[pageParamName] = 1;
+        params[perPageParamName] = perPage ?? params[perPageParamName];
+
+        while (true){
+            console.log("Querying page", params[pageParamName], `(${result.length} elements loaded)`);
+            let data = await this.execute(client, params, limiter, silentErrors, maxTries);
+
+            if (!data) throw (this.#getLog("error", params) ?? "Request failed.") + "(in paginated execution, at page " + params[pageParamName] + ")";
+
+            let localResult = deep_get(data, collectionPathInQuery);
+
+            if (!localResult) {
+                console.warn(`The given path ${collectionPathInQuery} does not point to anything.`);
+                return null;
+            }
+            
+            if (!localResult.push) throw "The given path does not point to an array."
+
+            if (localResult.length < 1) break;
+
+            result = result.concat(localResult);
+            params[pageParamName]++;
+
+            if (delay)
+                await new Promise(r => setTimeout(r, delay));
+        }
+
+        return result;
+    }
+}

package/src/queryLimiter.js

@@ -0,0 +1,137 @@
+//i am a god of JS
+
+/**
+ * Dummy client class that's only used in the JSDoc. 
+ * In a real use case, the user will have their own client class.
+ */
+export class Client {
+    request(){}
+}
+
+export class TimedQuerySemaphore {
+    /**
+     * @typedef {{client: Client, schema: string, 
+     *  params: {[varName: string]: value}, 
+     *  resolve: (value: any) => void, 
+     *  reject: (reason?: any) => void}
+     * } Query
+     */
+
+    /**@type {Query[]} */
+    #queue = [];    
+
+    /**@type {NodeJS.Timeout[]} */
+    #timers = [];
+
+    /**@type {number} */
+    #counter;
+
+    /**@type {number}*/
+    #delay;
+
+    /**
+     * 
+     * @param {number} size Semaphore counter initial value
+     * @param {number} delay 
+     */
+    constructor(size, delay){
+        this.#counter = size;
+        this.#delay = delay;
+    }
+
+    #startTimeout(){
+        let t = setTimeout(() => {
+            this.#release();
+        }, this.#delay); 
+        this.#timers.push(t);
+    }
+
+    /**
+     * @param {Client} client 
+     * @param {string} schema 
+     * @param {{[varName: string]: value}} params 
+     * @returns 
+     */
+    #execute(client, schema, params){
+        //console.log("Executing", params);
+
+        this.#startTimeout();
+        
+        return client.request(schema, params);
+
+        /*return new Promise((resolve) => setTimeout(() => {
+            resolve(schema);
+        }, 500))*/
+    }
+
+    /**
+     * @param {Query} query 
+     * @returns 
+     */
+    #executeQuery(query){
+        return this.#execute(query.client, query.schema, query.params);
+    }
+
+    /**
+     * Executes the given query with the given GraphQL Client
+     * @param {Client} client 
+     * @param {string} schema 
+     * @param {{[varName: string]: value}} params 
+     * @returns 
+     */
+    execute(client, schema, params){
+        if (this.#counter > 0){
+            this.#counter--;
+            //console.log("A ticket was available !", params);
+            return this.#execute(client, schema, params);
+        } else {
+            //console.log("No ticket vailable. Queueing.", params)
+            return new Promise((resolve, reject) =>  this.#queue.push({client, schema, params, resolve, reject}));
+        }
+    }
+
+    #release(){
+        //console.error("Release");
+        let query = this.#queue.shift();
+        if (query){
+            //console.error("A query was queued. Executing :", query.params);
+            this.#executeQuery(query)
+                .then(res => query.resolve(res))
+                .catch(err => query.reject(err));
+        } else {
+            this.#counter++;
+        }
+    }
+
+    stop(){
+        for (let timer of this.#timers){
+            clearTimeout(timer);
+        }
+    }
+}
+
+export class ClockQueryLimiter extends TimedQuerySemaphore {
+    /** @param {number} rpm */
+    constructor(rpm){
+        super(1, 60000 / rpm);
+    }
+}
+
+export class StartGGClockQueryLimiter extends ClockQueryLimiter {
+    constructor(){
+        super(60);
+    }
+}
+
+export class DelayQueryLimiter extends TimedQuerySemaphore {
+    /** @param {number} rpm */
+    constructor(rpm){
+        super (rpm, 60000);
+    }
+}
+
+export class StartGGDelayQueryLimiter extends DelayQueryLimiter {
+    constructor(){
+        super(60)
+    }
+}