@jondotsoy/pika 0.1.1

package/lib/esm/flow/utils/file.d.ts

@@ -0,0 +1,17 @@
+type FileEncoding = "utf-8";
+export declare class File {
+    readonly path: string | URL;
+    readonly options: {
+        encoding?: FileEncoding;
+    };
+    readonly encoding: FileEncoding;
+    constructor(path: string | URL, options?: {
+        encoding?: FileEncoding;
+    });
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    json<T>(): Promise<T>;
+    exists(): Promise<boolean>;
+    write(data: string | ArrayBuffer | object): Promise<void>;
+}
+export {};

package/lib/esm/flow/utils/file.js

@@ -0,0 +1,52 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+export class File {
+    path;
+    options;
+    encoding;
+    constructor(path, options = {}) {
+        this.path = path;
+        this.options = options;
+        this.encoding = options.encoding ?? "utf-8";
+    }
+    async arrayBuffer() {
+        const buffer = await fs.readFile(this.path);
+        return new Uint8Array(buffer).buffer;
+    }
+    async text() {
+        const buffer = await this.arrayBuffer();
+        return new TextDecoder(this.encoding).decode(buffer);
+    }
+    async json() {
+        const text = await this.text();
+        return JSON.parse(text);
+    }
+    async exists() {
+        try {
+            await fs.access(this.path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async write(data) {
+        const encod = {
+            object: (value) => new TextEncoder(this.encoding).encode(JSON.stringify(value)).buffer,
+            string: (value) => new TextEncoder(this.encoding).encode(value).buffer,
+            buffer: (value) => value,
+        };
+        const type = data instanceof ArrayBuffer ? "buffer" : typeof data;
+        const payload = encod[typeof data]?.(data);
+        if (payload === undefined) {
+            throw new Error("Unsupported data type for writing");
+        }
+        const relativePathname = this.path instanceof URL ? this.path.pathname : this.path;
+        const abspath = path.isAbsolute(relativePathname)
+            ? relativePathname
+            : path.resolve(process.cwd(), relativePathname);
+        const dir = path.dirname(abspath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(abspath, new Uint8Array(payload), this.encoding);
+    }
+}

package/lib/esm/flow/utils/observable-set.d.ts

@@ -0,0 +1,9 @@
+export declare class ObservableSet<T> extends Set<T> {
+    private _events;
+    addEventListener: any;
+    removeEventListener: any;
+    add(value: T): this;
+}
+export declare function getNextAvailable<T>(set: ObservableSet<T>, options?: {
+    signal?: AbortSignal;
+}): Promise<T | null>;

package/lib/esm/flow/utils/observable-set.js

@@ -0,0 +1,31 @@
+import { EventManager } from "./event-manager.js";
+export class ObservableSet extends Set {
+    _events = new EventManager();
+    addEventListener = this._events.addEventListener.bind(this._events);
+    removeEventListener = this._events.removeEventListener.bind(this._events);
+    add(value) {
+        const result = super.add(value);
+        this._events.emit("add", value);
+        return result;
+    }
+}
+// Helper function to get the next available item from an ObservableSet, waiting if necessary
+export async function getNextAvailable(set, options) {
+    let active = true;
+    while (active) {
+        for (const item of set) {
+            set.delete(item);
+            return item;
+        }
+        await new Promise((r) => {
+            const resolvePromise = () => r();
+            set.addEventListener("add", resolvePromise, { once: true });
+            options?.signal?.addEventListener("abort", () => {
+                set.removeEventListener("add", resolvePromise);
+                active = false;
+                r();
+            });
+        });
+    }
+    return null;
+}

package/lib/esm/flow/utils/queue.d.ts

@@ -0,0 +1,32 @@
+import { ObservableSet } from "./observable-set.js";
+type Handler<T> = (item: T) => Promise<void>;
+declare enum WorkerStatus {
+    Idle = "idle",
+    Processing = "processing",
+    Stopped = "stopped"
+}
+export declare class Worker<T> {
+    readonly observableSet: ObservableSet<T>;
+    readonly handler: Handler<T>;
+    private options?;
+    private active;
+    private _status;
+    private _process;
+    constructor(observableSet: ObservableSet<T>, handler: Handler<T>, options?: {
+        signal?: AbortSignal;
+    } | undefined, active?: boolean, _status?: WorkerStatus);
+    private start;
+    get status(): WorkerStatus;
+    stop(): void;
+}
+export declare class Queue<T> {
+    readonly options?: {} | undefined;
+    private _items;
+    private _workers;
+    constructor(options?: {} | undefined);
+    get workers(): number;
+    get size(): number;
+    enqueue(item: T): void;
+    subscribe(handler: Handler<T>): () => void;
+}
+export {};

package/lib/esm/flow/utils/queue.js

@@ -0,0 +1,86 @@
+import { getNextAvailable, ObservableSet } from "./observable-set.js";
+var SubscriptionStatus;
+(function (SubscriptionStatus) {
+    SubscriptionStatus["Idle"] = "idle";
+    SubscriptionStatus["Processing"] = "processing";
+})(SubscriptionStatus || (SubscriptionStatus = {}));
+var WorkerStatus;
+(function (WorkerStatus) {
+    WorkerStatus["Idle"] = "idle";
+    WorkerStatus["Processing"] = "processing";
+    WorkerStatus["Stopped"] = "stopped";
+})(WorkerStatus || (WorkerStatus = {}));
+export class Worker {
+    observableSet;
+    handler;
+    options;
+    active;
+    _status;
+    _process;
+    constructor(observableSet, handler, options, active = true, _status = WorkerStatus.Idle) {
+        this.observableSet = observableSet;
+        this.handler = handler;
+        this.options = options;
+        this.active = active;
+        this._status = _status;
+        this._process = this.start();
+        options?.signal?.addEventListener("abort", () => {
+            this.active = false;
+        });
+    }
+    async start() {
+        while (this.active) {
+            const item = await getNextAvailable(this.observableSet, {
+                signal: this.options?.signal,
+            });
+            if (item === null) {
+                continue;
+            }
+            try {
+                this._status = WorkerStatus.Processing;
+                await this.handler(item);
+            }
+            catch (error) {
+                console.error("Error processing item in worker:", error);
+            }
+            finally {
+                this._status = WorkerStatus.Idle;
+            }
+        }
+    }
+    get status() {
+        return this._status;
+    }
+    stop() {
+        this.active = false;
+    }
+}
+export class Queue {
+    options;
+    _items = new ObservableSet();
+    _workers = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get workers() {
+        return this._workers.size;
+    }
+    get size() {
+        return this._items.size;
+    }
+    enqueue(item) {
+        this._items.add(item);
+    }
+    subscribe(handler) {
+        const abortController = new AbortController();
+        const worker = new Worker(this._items, handler, {
+            signal: abortController.signal,
+        });
+        this._workers.add(worker);
+        return () => {
+            abortController.abort();
+            worker.stop();
+            this._workers.delete(worker);
+        };
+    }
+}

package/lib/esm/flow/worker_ctx.d.ts

@@ -0,0 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export declare const processingJobContext: AsyncLocalStorage<{
+    processingId: string;
+    currentJobId: string | null;
+}>;

package/lib/esm/flow/worker_ctx.js

@@ -0,0 +1,2 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const processingJobContext = new AsyncLocalStorage();

package/lib/esm/http/index.d.ts

@@ -0,0 +1,32 @@
+import { type Credentials } from "../auth/index.js";
+export type BodyParser = (res: Response) => Promise<any>;
+export type WrapFetchOptions = {
+    headers?: Record<string, string>;
+    bodyParser?: BodyParser;
+    credentials?: Credentials;
+};
+export type WrapFetchResult = {
+    status: number;
+    headers: Record<string, string>;
+    body: any;
+    items: any[];
+};
+export declare function wrapFetch(url: string, options?: WrapFetchOptions): Promise<WrapFetchResult>;
+export type PaginationOptions = {
+    nextPage: (ctx: {
+        body: any;
+    }) => string | null;
+    items: (ctx: {
+        body: any;
+    }) => any[] | null;
+};
+export type HttpOptions = WrapFetchOptions & {
+    pagination?: PaginationOptions;
+};
+export type HttpResult = {
+    status: number | null;
+    headers: Record<string, string> | null;
+    body: any | null;
+    items: any[];
+};
+export declare function http(url: string, options?: HttpOptions): Promise<HttpResult>;

package/lib/esm/http/index.js

@@ -0,0 +1,54 @@
+import { parse as parseYaml } from "yaml";
+import { Placement } from "../auth/index.js";
+const defaultBodyParser = async (res) => {
+    const ct = res.headers.get("content-type") ?? "";
+    const text = await res.text();
+    if (ct.includes("application/json") || ct.includes("+json"))
+        return JSON.parse(text);
+    if (ct.includes("yaml") || ct.includes("x-yaml"))
+        return parseYaml(text);
+    try {
+        return JSON.parse(text);
+    }
+    catch { }
+    try {
+        return parseYaml(text);
+    }
+    catch { }
+    return text;
+};
+export async function wrapFetch(url, options = {}) {
+    const { headers: reqHeaders, bodyParser = defaultBodyParser, credentials, } = options;
+    const mergedHeaders = { ...reqHeaders };
+    let fetchUrl = url;
+    if (credentials) {
+        const token = await credentials.value();
+        if (credentials.placement === Placement.query) {
+            const u = new URL(fetchUrl);
+            u.searchParams.set(credentials.parameterName ?? "token", token);
+            fetchUrl = u.toString();
+        }
+        else {
+            mergedHeaders[credentials.parameterName ?? "Authorization"] = token;
+        }
+    }
+    const res = await fetch(fetchUrl, { headers: mergedHeaders });
+    const body = await bodyParser(res);
+    const resHeaders = Object.fromEntries(res.headers.entries());
+    const items = Array.isArray(body) ? body : [body];
+    return { status: res.status, headers: resHeaders, body, items };
+}
+export async function http(url, options = {}) {
+    const { pagination, ...fetchOpts } = options;
+    if (!pagination) {
+        return wrapFetch(url, fetchOpts);
+    }
+    const allItems = [];
+    let nextUrl = url;
+    while (nextUrl) {
+        const { body } = await wrapFetch(nextUrl, fetchOpts);
+        allItems.push(...(pagination.items({ body }) ?? []));
+        nextUrl = pagination.nextPage({ body });
+    }
+    return { status: null, headers: null, body: null, items: allItems };
+}

package/lib/esm/telemetry/metrics/gateway.d.ts

@@ -0,0 +1,2 @@
+import { Pushgateway } from "prom-client";
+export declare const gateway: Pushgateway<"text/plain; version=0.0.4; charset=utf-8"> | null;

package/lib/esm/telemetry/metrics/gateway.js

@@ -0,0 +1,6 @@
+import { Pushgateway } from "prom-client";
+import { registry } from "./registry.js";
+import { telemetryUrl } from "./telemetry-url.js";
+export const gateway = telemetryUrl
+    ? new Pushgateway(telemetryUrl, {}, registry)
+    : null;

package/lib/esm/telemetry/metrics/job-gauges.d.ts

@@ -0,0 +1,13 @@
+import { Gauge } from "prom-client";
+/**
+ * Node Graph metrics for Grafana
+ * Docs: https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/visualizations/node-graph/
+ *
+ * Nodes frame fields: id, title, arc__success, arc__failed, detail__duration
+ * Edges frame fields: id, source, target
+ */
+export declare const jobDuration: Gauge<"id" | "title">;
+export declare const jobArcSuccess: Gauge<"id">;
+export declare const jobArcFailed: Gauge<"id">;
+export declare const jobEdge: Gauge<"id" | "target" | "source">;
+export declare const jobActive: Gauge<"id">;

package/lib/esm/telemetry/metrics/job-gauges.js

@@ -0,0 +1,39 @@
+import { Gauge } from "prom-client";
+import { registry } from "./registry.js";
+/**
+ * Node Graph metrics for Grafana
+ * Docs: https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/visualizations/node-graph/
+ *
+ * Nodes frame fields: id, title, arc__success, arc__failed, detail__duration
+ * Edges frame fields: id, source, target
+ */
+export const jobDuration = new Gauge({
+    name: "job_duration_seconds",
+    help: "Last execution duration of a job in seconds",
+    labelNames: ["id", "title"],
+    registers: [registry],
+});
+export const jobArcSuccess = new Gauge({
+    name: "job_arc_success",
+    help: "Arc ratio of successful executions (0-1) for node graph",
+    labelNames: ["id"],
+    registers: [registry],
+});
+export const jobArcFailed = new Gauge({
+    name: "job_arc_failed",
+    help: "Arc ratio of failed executions (0-1) for node graph",
+    labelNames: ["id"],
+    registers: [registry],
+});
+export const jobEdge = new Gauge({
+    name: "job_edge",
+    help: "Edge between two jobs in the node graph",
+    labelNames: ["id", "source", "target"],
+    registers: [registry],
+});
+export const jobActive = new Gauge({
+    name: "job_active",
+    help: "1 if the job is currently active, 0 otherwise",
+    labelNames: ["id"],
+    registers: [registry],
+});

package/lib/esm/telemetry/metrics/job-store.d.ts

@@ -0,0 +1,3 @@
+export declare const startJob: (id: string) => void;
+export declare const endJob: (id: string, title: string, success: boolean) => void;
+export declare const recordEdge: (parentJobId: string, jobId: string) => void;

package/lib/esm/telemetry/metrics/job-store.js

@@ -0,0 +1,31 @@
+import { push } from "./push.js";
+import { jobDuration, jobArcSuccess, jobArcFailed, jobEdge, jobActive, } from "./job-gauges.js";
+const pendingStarts = new Map();
+const counters = new Map();
+export const startJob = (id) => {
+    pendingStarts.set(id, performance.now());
+    jobActive.set({ id }, 1);
+    push(id).catch(() => { });
+};
+export const endJob = (id, title, success) => {
+    jobActive.set({ id }, 0);
+    const startedAt = pendingStarts.get(id);
+    if (startedAt !== undefined) {
+        const duration = (performance.now() - startedAt) / 1000;
+        jobDuration.set({ id, title }, duration);
+        pendingStarts.delete(id);
+    }
+    const counts = counters.get(id) ?? { success: 0, failed: 0 };
+    if (success)
+        counts.success++;
+    else
+        counts.failed++;
+    counters.set(id, counts);
+    const total = counts.success + counts.failed;
+    jobArcSuccess.set({ id }, counts.success / total);
+    jobArcFailed.set({ id }, counts.failed / total);
+    push(id).catch(() => { });
+};
+export const recordEdge = (parentJobId, jobId) => {
+    jobEdge.set({ id: `${parentJobId}->${jobId}`, source: parentJobId, target: jobId }, 1);
+};

package/lib/esm/telemetry/metrics/push.d.ts

@@ -0,0 +1 @@
+export declare const push: (jobName: string) => Promise<void>;

package/lib/esm/telemetry/metrics/push.js

@@ -0,0 +1,4 @@
+import { gateway } from "./gateway.js";
+export const push = async (jobName) => {
+    await gateway?.push({ jobName });
+};

package/lib/esm/telemetry/metrics/registry.d.ts

@@ -0,0 +1,2 @@
+import { Registry } from "prom-client";
+export declare const registry: Registry<"text/plain; version=0.0.4; charset=utf-8">;

package/lib/esm/telemetry/metrics/registry.js

@@ -0,0 +1,2 @@
+import { Registry } from "prom-client";
+export const registry = new Registry();

package/lib/esm/telemetry/metrics/telemetry-url.d.ts

@@ -0,0 +1 @@
+export declare const telemetryUrl: string | undefined;

package/lib/esm/telemetry/metrics/telemetry-url.js

@@ -0,0 +1 @@
+export const telemetryUrl = process.env.TELEMETRY_URL;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@jondotsoy/pika",
+  "version": "0.1.1",
+  "type": "module",
+  "types": "./lib/esm/flow/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/esm/flow/index.d.ts",
+      "default": "./lib/esm/flow/index.js"
+    },
+    "./loader": {
+      "types": "./lib/esm/flow/loader.d.ts",
+      "default": "./lib/esm/flow/loader.js"
+    },
+    "./http": {
+      "types": "./lib/esm/http/index.d.ts",
+      "default": "./lib/esm/http/index.js"
+    },
+    "./auth": {
+      "types": "./lib/esm/auth/index.d.ts",
+      "default": "./lib/esm/auth/index.js"
+    }
+  },
+  "bin": {
+    "pika": "lib/esm/cli/index.js"
+  },
+  "scripts": {
+    "pack": "npm pack",
+    "fmt": "prettier -w .",
+    "lint": "prettier -c .",
+    "prepack": "tsc -p tsconfig.esm.json"
+  },
+  "dependencies": {
+    "@jondotsoy/flags": "3.2.1",
+    "@jondotsoy/style-text": "0.9.2",
+    "prom-client": "15.1.3",
+    "temporal-polyfill": "0.3.2",
+    "ulid": "3.0.2",
+    "yaml": "2.8.2",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "@types/node": "25.5.0",
+    "prettier": "3.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "5.9.3"
+  },
+  "files": [
+    "lib/"
+  ],
+  "license": "MIT",
+  "author": "Jonathan Delgado <hi@jon.soy> (https://jon.soy)"
+}