@wxn0brp/vql-client 0.0.1

package/.github/workflows/build.yml

@@ -0,0 +1,25 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "*"
+
+  workflow_dispatch:
+
+concurrency:
+  group: build-main
+  cancel-in-progress: true
+
+jobs:
+  build:
+    uses: wxn0brP/workflow-dist/.github/workflows/build-ts.yml@main
+    with:
+      scriptsHandling: "remove-all"
+      customCommands: "npm run minify"
+      publishToNpm: true
+    
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wxn0brP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @wxn0brp/vql-client
+
+Minimalistic, pluggable client for **VQL** query execution.
+
+Supports:
+
+- ✅ ESM (`import`)
+- ✅ CJS (`require`)
+- ✅ CDN / `<script>` (`VQLClient`)
+- ✅ Fully typed with TypeScript
+- ✅ Custom transport layers and lifecycle hooks
+
+## 📦 Installation
+
+### NPM
+
+```bash
+npm install @wxn0brp/vql-client
+```
+
+```ts
+import { fetchVQL, initVQLClient, resetVQLClient } from "@wxn0brp/vql-client";
+
+const result = await fetchVQL("db1 user! s._id = xyz");
+```
+
+### CDN
+
+```html
+<script src="/dist/vql-client.min.js"></script>
+<script>
+  VQLClient.fetchVQL("db1 user! s._id = xyz").then(console.log);
+</script>
+```
+
+You can also serve `vql-client.min.js` from your own CDN or static server.
+
+## 🧠 Usage
+
+### `fetchVQL<T = any>(query: string | object): Promise<T>`
+
+Executes a VQL query and returns the result (unwrapped from `{ result }`, unless an error is present).
+
+### `initVQLClient(config: { transport?: fn, hooks?: {...} })`
+
+Customize client behavior.
+
+#### Example – custom transport and hooks:
+
+```ts
+initVQLClient({
+  transport: async (query) => {
+    return await fetch("/VQL", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query })
+    }).then(res => res.json());
+  },
+  hooks: {
+    onStart: (q) => console.log("VQL start", q),
+    onEnd: (q, ms, r) => console.log("VQL end", ms + "ms", r),
+    onError: (q, e) => console.error("VQL error", e)
+  }
+});
+```
+
+### `resetVQLClient()`
+
+Reset transport and hooks to default.
+
+## ✈️ Default Transport
+
+```ts
+defaultFetchTransport(query): Promise<any>
+```
+
+Sends:
+
+```
+POST /VQL
+Content-Type: application/json
+Body: { query }
+```
+
+Returns:
+
+```
+{
+  result: any,
+  err?: string
+}
+```
+
+Use `initVQLClient({ transport })` to override with WebSocket, RPC, etc.
+
+## 📁 Output Files
+
+```
+dist/
+├── index.js               # ESM build (import)
+├── index.d.ts             # TypeScript types
+├── vql-client.cjs         # CommonJS build (require)
+├── vql-client.min.js      # Global (CDN, window.VQLClient)
+```
+
+## 🧾 Typings in Browser
+
+You can manually copy `index.d.ts` to your local project or declare global types:
+
+```ts
+declare const VQLClient: {
+  fetchVQL<T = any>(query: string | object): Promise<T>;
+  initVQLClient(config: {
+    transport?: (query: string | object) => Promise<any>,
+    hooks?: {
+      onStart?: (query: string | object) => void,
+      onEnd?: (query: string | object, ms: number, result: any) => void,
+      onError?: (query: string | object, error: unknown) => void
+    }
+  }): void;
+  resetVQLClient(): void;
+  defaultFetchTransport(query: string | object): Promise<any>;
+};
+```
+
+## 🧪 Example
+
+```ts
+const result = await fetchVQL("api getUser! s._id = abc123");
+console.log(result.name);
+```
+
+## 📜 License
+
+MIT © wxn0brP

package/build.js

@@ -0,0 +1,33 @@
+import esbuild from "esbuild";
+
+const sharedConfig = {
+    entryPoints: ["src/index.ts"],
+    bundle: true,
+    sourcemap: false,
+    target: "es2017",
+};
+
+Promise.all([
+    // IIFE + minified
+    esbuild.build({
+        ...sharedConfig,
+        format: "iife",
+        globalName: "VQLClient",
+        minify: true,
+        outfile: "dist/vql-client.min.js",
+    }),
+
+    // CommonJS - require
+    esbuild.build({
+        ...sharedConfig,
+        format: "cjs",
+        outfile: "dist/vql-client.cjs",
+    }),
+])
+    .then(() => {
+        console.log("✅ Build complete");
+    })
+    .catch((e) => {
+        console.error("❌ Build failed:", e);
+        process.exit(1);
+    });

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export type VQLQuery = string | object;
+export type VQLResult<T = any> = Promise<T>;
+export type VQLTransport = (query: VQLQuery) => VQLResult;
+export type VQLHooks = {
+    onStart?: (query: VQLQuery) => void;
+    onEnd?: (query: VQLQuery, durationMs: number, result: any) => void;
+    onError?: (query: VQLQuery, error: unknown) => void;
+};
+export declare function initVQLClient(config: {
+    transport?: VQLTransport;
+    hooks?: VQLHooks;
+}): void;
+export declare function fetchVQL<T = any>(query: VQLQuery): Promise<T>;
+export declare function resetVQLClient(): void;
+export declare function defaultFetchTransport(query: VQLQuery): Promise<any>;

package/dist/index.js

@@ -0,0 +1,51 @@
+let transport = defaultFetchTransport;
+let hooks = {};
+export function initVQLClient(config) {
+    if (config.transport)
+        transport = config.transport;
+    if (config.hooks)
+        hooks = config.hooks;
+}
+export async function fetchVQL(query) {
+    const start = Date.now();
+    try {
+        hooks.onStart?.(query);
+        const res = await transport(query);
+        const duration = Date.now() - start;
+        hooks.onEnd?.(query, duration, res);
+        if (res?.err) {
+            const error = new Error(res.err);
+            hooks.onError?.(query, error);
+            throw error;
+        }
+        return res?.result ?? res;
+    }
+    catch (e) {
+        hooks.onError?.(query, e);
+        throw e;
+    }
+}
+export function resetVQLClient() {
+    transport = defaultFetchTransport;
+    hooks = {};
+}
+export async function defaultFetchTransport(query) {
+    const res = await fetch("/VQL", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ query })
+    });
+    if (!res.ok)
+        throw new Error(`VQL request failed: ${res.status}`);
+    return await res.json();
+}
+if (typeof window !== "undefined") {
+    window.VQLClient = {
+        fetchVQL,
+        initVQLClient,
+        resetVQLClient,
+        defaultFetchTransport
+    };
+}

package/dist/vql-client.cjs

@@ -0,0 +1,75 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  defaultFetchTransport: () => defaultFetchTransport,
+  fetchVQL: () => fetchVQL,
+  initVQLClient: () => initVQLClient,
+  resetVQLClient: () => resetVQLClient
+});
+module.exports = __toCommonJS(index_exports);
+var transport = defaultFetchTransport;
+var hooks = {};
+function initVQLClient(config) {
+  if (config.transport) transport = config.transport;
+  if (config.hooks) hooks = config.hooks;
+}
+async function fetchVQL(query) {
+  var _a, _b, _c, _d, _e;
+  const start = Date.now();
+  try {
+    (_a = hooks.onStart) == null ? void 0 : _a.call(hooks, query);
+    const res = await transport(query);
+    const duration = Date.now() - start;
+    (_b = hooks.onEnd) == null ? void 0 : _b.call(hooks, query, duration, res);
+    if (res == null ? void 0 : res.err) {
+      const error = new Error(res.err);
+      (_c = hooks.onError) == null ? void 0 : _c.call(hooks, query, error);
+      throw error;
+    }
+    return (_d = res == null ? void 0 : res.result) != null ? _d : res;
+  } catch (e) {
+    (_e = hooks.onError) == null ? void 0 : _e.call(hooks, query, e);
+    throw e;
+  }
+}
+function resetVQLClient() {
+  transport = defaultFetchTransport;
+  hooks = {};
+}
+async function defaultFetchTransport(query) {
+  const res = await fetch("/VQL", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ query })
+  });
+  if (!res.ok) throw new Error(`VQL request failed: ${res.status}`);
+  return await res.json();
+}
+if (typeof window !== "undefined") {
+  window.VQLClient = {
+    fetchVQL,
+    initVQLClient,
+    resetVQLClient,
+    defaultFetchTransport
+  };
+}

package/dist/vql-client.min.js

@@ -0,0 +1 @@
+var VQLClient=(()=>{var Q=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var l=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var x=(t,r)=>{for(var a in r)Q(t,a,{get:r[a],enumerable:!0})},E=(t,r,a,i)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of l(r))!T.call(t,o)&&o!==a&&Q(t,o,{get:()=>r[o],enumerable:!(i=f(r,o))||i.enumerable});return t};var h=t=>E(Q({},"__esModule",{value:!0}),t);var m={};x(m,{defaultFetchTransport:()=>s,fetchVQL:()=>d,initVQLClient:()=>V,resetVQLClient:()=>c});var u=s,n={};function V(t){t.transport&&(u=t.transport),t.hooks&&(n=t.hooks)}async function d(t){var a,i,o,p,y;let r=Date.now();try{(a=n.onStart)==null||a.call(n,t);let e=await u(t),w=Date.now()-r;if((i=n.onEnd)==null||i.call(n,t,w,e),e!=null&&e.err){let L=new Error(e.err);throw(o=n.onError)==null||o.call(n,t,L),L}return(p=e==null?void 0:e.result)!=null?p:e}catch(e){throw(y=n.onError)==null||y.call(n,t,e),e}}function c(){u=s,n={}}async function s(t){let r=await fetch("/VQL",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({query:t})});if(!r.ok)throw new Error(`VQL request failed: ${r.status}`);return await r.json()}typeof window!="undefined"&&(window.VQLClient={fetchVQL:d,initVQLClient:V,resetVQLClient:c,defaultFetchTransport:s});return h(m);})();

package/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "@wxn0brp/vql-client",
+    "version": "0.0.1",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "author": "wxn0brP",
+    "license": "MIT",
+    "type": "module",
+    "scripts": {
+        "build": "tsc && tsc-alias",
+        "minify": "node build.js"
+    },
+    "devDependencies": {
+        "esbuild": "^0.25.4",
+        "tsc-alias": "^1.8.10",
+        "typescript": "^5.7.3"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs",
+            "default": "./dist/index.js"
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+export type VQLQuery = string | object;
+export type VQLResult<T = any> = Promise<T>;
+export type VQLTransport = (query: VQLQuery) => VQLResult;
+export type VQLHooks = {
+    onStart?: (query: VQLQuery) => void;
+    onEnd?: (query: VQLQuery, durationMs: number, result: any) => void;
+    onError?: (query: VQLQuery, error: unknown) => void;
+};
+
+let transport: VQLTransport = defaultFetchTransport;
+let hooks: VQLHooks = {};
+
+export function initVQLClient(config: {
+    transport?: VQLTransport,
+    hooks?: VQLHooks
+}) {
+    if (config.transport) transport = config.transport;
+    if (config.hooks) hooks = config.hooks;
+}
+
+export async function fetchVQL<T = any>(query: VQLQuery): Promise<T> {
+    const start = Date.now();
+    try {
+        hooks.onStart?.(query);
+
+        const res = await transport(query);
+
+        const duration = Date.now() - start;
+        hooks.onEnd?.(query, duration, res);
+
+        if (res?.err) {
+            const error = new Error(res.err);
+            hooks.onError?.(query, error);
+            throw error;
+        }
+
+        return res?.result ?? res;
+    } catch (e) {
+        hooks.onError?.(query, e);
+        throw e;
+    }
+}
+
+export function resetVQLClient() {
+    transport = defaultFetchTransport;
+    hooks = {};
+}
+
+export async function defaultFetchTransport(query: VQLQuery): Promise<any> {
+    const res = await fetch("/VQL", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ query })
+    });
+
+    if (!res.ok) throw new Error(`VQL request failed: ${res.status}`);
+    return await res.json();
+}
+
+// Export global for CDN use
+if (typeof window !== "undefined") {
+    (window as any).VQLClient = {
+        fetchVQL,
+        initVQLClient,
+        resetVQLClient,
+        defaultFetchTransport
+    };
+}

package/suglite.json

@@ -0,0 +1,10 @@
+{
+    "cmd": "yarn build",
+    "watch": [
+        "src"
+    ],
+    "restart_cmd": "clear",
+    "events": {
+        "rs": "clear"
+    }
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+    "compilerOptions": {
+        "module": "ES2022",
+        "target": "ES2022",
+        "moduleResolution": "node",
+        "paths": {},
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "outDir": "./dist",
+        "inlineSourceMap": false,
+        "sourceMap": false,
+        "declaration": true,
+        "removeComments": true
+    },
+    "include": [
+       "./src"
+    ],
+    "exclude": [
+        "node_modules"
+    ],
+    "tsc-alias": {
+        "resolveFullPaths": true,
+        "verbose": false
+    }
+}