@chainfuse/helpers 0.0.2

package/README.md

@@ -0,0 +1,11 @@
+# `@chainfuse/helpers`
+
+> TODO: description
+
+## Usage
+
+```
+import helpers from '@chainfuse/helpers';
+
+// TODO: DEMONSTRATE API
+```

package/dist/buffers.d.mts

@@ -0,0 +1,12 @@
+import type { UndefinedProperties } from '@chainfuse/types';
+import type { PrefixedUuid, UuidExport } from '@chainfuse/types/d1';
+export declare class BufferHelpers {
+    static bufferFromHex(hex: UuidExport['hex']): Promise<UuidExport['blob']>;
+    static bufferToHex(buffer: UuidExport['blob']): Promise<UuidExport['hex']>;
+    static get generateUuid(): Promise<UuidExport>;
+    static uuidConvert(input: UuidExport['blob']): Promise<UuidExport>;
+    static uuidConvert(prefixedUtf: PrefixedUuid): Promise<UuidExport>;
+    static uuidConvert(input: UuidExport['utf8']): Promise<UuidExport>;
+    static uuidConvert(input: UuidExport['hex']): Promise<UuidExport>;
+    static uuidConvert(input: undefined): Promise<UndefinedProperties<UuidExport>>;
+}

package/dist/buffers.mjs

@@ -0,0 +1,76 @@
+import { CryptoHelpers } from './crypto.mjs';
+export class BufferHelpers {
+    static bufferFromHex(hex) {
+        return (import('node:buffer')
+            .then(({ Buffer }) => {
+            const mainBuffer = Buffer.from(hex, 'hex');
+            return mainBuffer.buffer.slice(mainBuffer.byteOffset, mainBuffer.byteOffset + mainBuffer.byteLength);
+        })
+            /**
+             * @link https://jsbm.dev/NHJHj31Zwm3OP
+             */
+            .catch(() => new Uint8Array(hex.length / 2).map((_, index) => parseInt(hex.slice(index * 2, index * 2 + 2), 16)).buffer));
+    }
+    static bufferToHex(buffer) {
+        return (import('node:buffer')
+            .then(({ Buffer }) => Buffer.from(buffer).toString('hex'))
+            /**
+             * @link https://jsbm.dev/AoXo8dEke1GUg
+             */
+            .catch(() => new Uint8Array(buffer).reduce((output, elem) => output + ('0' + elem.toString(16)).slice(-2), '')));
+    }
+    static get generateUuid() {
+        return Promise.all([CryptoHelpers.secretBytes(16), import('uuid')]).then(([random, { v7: uuidv7 }]) => {
+            const uuid = uuidv7({ random });
+            const uuidHex = uuid.replaceAll('-', '');
+            return this.bufferFromHex(uuidHex).then((blob) => ({
+                utf8: uuid,
+                hex: uuidHex,
+                blob,
+            }));
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+    static uuidConvert(input) {
+        if (input) {
+            if (typeof input === 'string') {
+                if (input.includes('-')) {
+                    let hex = input.replaceAll('-', '');
+                    if (input.includes('_')) {
+                        input = input.split('_')[1];
+                        hex = hex.split('_')[1];
+                    }
+                    return this.bufferFromHex(hex).then((blob) => ({
+                        utf8: input,
+                        hex,
+                        blob,
+                    }));
+                }
+                else {
+                    const hex = input;
+                    return this.bufferFromHex(hex).then((blob) => ({
+                        utf8: `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`,
+                        hex,
+                        blob,
+                    }));
+                }
+            }
+            else {
+                const blob = input;
+                return this.bufferToHex(blob).then((hex) => ({
+                    utf8: `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`,
+                    hex,
+                    blob,
+                }));
+            }
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/require-await
+            return (async () => ({
+                utf8: undefined,
+                hex: undefined,
+                blob: undefined,
+            }))();
+        }
+    }
+}

package/dist/crypto.d.mts

@@ -0,0 +1,11 @@
+export declare class CryptoHelpers {
+    static secretBytes(length: number): Promise<Buffer | Uint8Array>;
+    static base16secret(length: number): Promise<string>;
+    static base62secret(length: number): Promise<string>;
+    static getHash(algorithm: 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512', input: string | ArrayBufferLike): Promise<string>;
+    /**
+     * @returns Fully formatted (double quote encapsulated) `ETag` header value
+     * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag#etag_value
+     */
+    static generateETag(response: Response, algorithm?: Parameters<typeof this.getHash>[0]): Promise<string>;
+}

package/dist/crypto.mjs

@@ -0,0 +1,56 @@
+import { BufferHelpers } from './buffers.mjs';
+export class CryptoHelpers {
+    static secretBytes(length) {
+        return import('node:crypto')
+            .then(({ randomBytes }) => randomBytes(length))
+            .catch(() => {
+            const randomBytes = new Uint8Array(length);
+            crypto.getRandomValues(randomBytes);
+            return randomBytes;
+        });
+    }
+    static base16secret(length) {
+        return this.secretBytes(length).then((bytes) => BufferHelpers.bufferToHex(bytes));
+    }
+    static base62secret(length) {
+        const LOWER_CHAR_SET = 'abcdefghijklmnopqrstuvwxyz';
+        const NUMBER_CHAR_SET = '0123456789';
+        const CHAR_SET = `${NUMBER_CHAR_SET}${LOWER_CHAR_SET}${LOWER_CHAR_SET.toUpperCase()}`;
+        return this.secretBytes(length).then((randomBytes) => {
+            /**
+             * @link https://jsbm.dev/x1F2ITy7RU8T2
+             */
+            let randomText = '';
+            for (const byte of randomBytes) {
+                // Map each byte to a character in the character set
+                const charIndex = byte % CHAR_SET.length;
+                randomText += CHAR_SET.charAt(charIndex);
+            }
+            return randomText;
+        });
+    }
+    static getHash(algorithm, input) {
+        return import('node:crypto')
+            .then(async ({ createHash }) => {
+            const hash = createHash(algorithm.replace('-', '').toLowerCase());
+            if (typeof input === 'string') {
+                hash.update(input);
+            }
+            else {
+                await import('node:buffer').then(({ Buffer }) => hash.update(Buffer.from(input)));
+            }
+            return hash.digest('hex');
+        })
+            .catch(() => crypto.subtle.digest(algorithm, typeof input === 'string' ? new TextEncoder().encode(input) : input).then((hashBuffer) => BufferHelpers.bufferToHex(hashBuffer)));
+    }
+    /**
+     * @returns Fully formatted (double quote encapsulated) `ETag` header value
+     * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag#etag_value
+     */
+    static generateETag(response, algorithm = 'SHA-512') {
+        return response
+            .clone()
+            .arrayBuffer()
+            .then((buffer) => this.getHash(algorithm, buffer).then((hex) => `"${hex}"`));
+    }
+}

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+export * from './buffers.mjs';
+export * from './crypto.mjs';
+export * from './net.mjs';
+export declare class Helpers {
+    static precisionFloat(input: string): number;
+    /**
+     * A wrapper around `Promise.allSettled()` that filters and returns only the fulfilled results. This method behaves like `Promise.allSettled()` where one promise failing doesn't stop others.
+     * However, like `Promise.all()`, it only returns the values of successfully fulfilled promises without needing to manually check their status.
+     *
+     * @param promises - An array of promises to be settled.
+     * @returns A promise that resolves to an array of fulfilled values from the input promises.
+     */
+    static getFulfilledResults<T extends unknown>(promises: PromiseLike<T>[]): Promise<Awaited<T>[]>;
+}

package/dist/index.mjs

@@ -0,0 +1,31 @@
+export * from './buffers.mjs';
+export * from './crypto.mjs';
+export * from './net.mjs';
+export class Helpers {
+    static precisionFloat(input) {
+        if (!input.includes('.')) {
+            // No decimal point means it's an integer, just return as a float
+            return parseFloat(input);
+        }
+        else {
+            if (input.endsWith('0')) {
+                // Replace the last '0' with '1' while keeping other characters unchanged
+                return parseFloat(input.substring(0, input.length - 1) + '1');
+            }
+            else {
+                // If last decimal is not zero, parse as usual
+                return parseFloat(input);
+            }
+        }
+    }
+    /**
+     * A wrapper around `Promise.allSettled()` that filters and returns only the fulfilled results. This method behaves like `Promise.allSettled()` where one promise failing doesn't stop others.
+     * However, like `Promise.all()`, it only returns the values of successfully fulfilled promises without needing to manually check their status.
+     *
+     * @param promises - An array of promises to be settled.
+     * @returns A promise that resolves to an array of fulfilled values from the input promises.
+     */
+    static getFulfilledResults(promises) {
+        return Promise.allSettled(promises).then((results) => results.filter((result) => result.status === 'fulfilled').map((result) => result.value));
+    }
+}

package/dist/net.d.mts

@@ -0,0 +1,22 @@
+import type { CustomLoging } from '@chainfuse/types';
+export declare class NetHelpers {
+    /**
+     * Removes the `body` property from a RequestInit object to reduce verbosity when logging.
+     *
+     * @param {RequestInit} [init={}] - The RequestInit object from which to remove the 'body' property. If not provided, an empty object will be used.
+     *
+     * @returns {RequestInit} The updated RequestInit object without the 'body' property.
+     */
+    static initBodyTrimmer(init?: RequestInit): RequestInit;
+    static stripSensitiveHeaders(originalHeaders?: Headers): Headers;
+    static cfApi(apiKey: string, cacheTtl?: number, logger?: CustomLoging): Promise<import("cloudflare").Cloudflare>;
+    static loggingFetch(info: Parameters<typeof fetch>[0], init: Parameters<typeof fetch>[1], body?: boolean, logger?: CustomLoging): Promise<Response>;
+    /**
+     * Parses the Server-Timing header and returns an object with the metrics.
+     * The object keys are the metric names (with optional descriptions), and the values are the duration of each metric or null if no duration is found.
+     *
+     * @param {string} [serverTimingHeader=''] - The Server-Timing header string.
+     * @returns {Record<string, number | null>} An object where keys are metric names (with optional descriptions) and values are the durations in milliseconds or null.
+     */
+    static serverTiming(serverTimingHeader?: string): Record<string, number | null>;
+}

package/dist/net.mjs

@@ -0,0 +1,280 @@
+import { CryptoHelpers } from './crypto.mjs';
+export class NetHelpers {
+    /**
+     * Removes the `body` property from a RequestInit object to reduce verbosity when logging.
+     *
+     * @param {RequestInit} [init={}] - The RequestInit object from which to remove the 'body' property. If not provided, an empty object will be used.
+     *
+     * @returns {RequestInit} The updated RequestInit object without the 'body' property.
+     */
+    static initBodyTrimmer(init = {}) {
+        if ('cf' in init)
+            delete init.cf;
+        delete init.body;
+        return init;
+    }
+    static stripSensitiveHeaders(originalHeaders = new Headers()) {
+        originalHeaders.delete('Set-Cookie');
+        originalHeaders.delete('Authorization');
+        return originalHeaders;
+    }
+    static cfApi(apiKey, cacheTtl, logger = false) {
+        return import('cloudflare').then(({ Cloudflare }) => new Cloudflare({
+            apiToken: apiKey,
+            fetch: (info, init) => 
+            // eslint-disable-next-line @typescript-eslint/no-misused-promises
+            new Promise(async (resolve) => {
+                const cacheKey = new Request(info, { ...init, headers: this.stripSensitiveHeaders(new Headers(init?.headers)) });
+                if (typeof logger === 'boolean') {
+                    if (logger) {
+                        await import('chalk')
+                            .then(({ Chalk }) => {
+                            const chalk = new Chalk({ level: 1 });
+                            console.debug(chalk.magenta('CF Fetch request'), chalk.magenta(cacheKey.url), JSON.stringify(this.initBodyTrimmer({ ...init, headers: Object.fromEntries(this.stripSensitiveHeaders(new Headers(init?.headers)).entries()) }), null, '\t'));
+                        })
+                            .catch(() => console.debug('CF Fetch request', cacheKey.url, JSON.stringify(this.initBodyTrimmer({ ...init, headers: Object.fromEntries(this.stripSensitiveHeaders(new Headers(init?.headers)).entries()) }), null, '\t')));
+                    }
+                }
+                else {
+                    logger(`CF Fetch request ${cacheKey.url} ${JSON.stringify(this.initBodyTrimmer({ ...init, headers: Object.fromEntries(this.stripSensitiveHeaders(new Headers(init?.headers)).entries()) }), null, '\t')}`);
+                }
+                if (cacheTtl) {
+                    const cfCacheRef = caches?.open('cfApi');
+                    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+                    if (cfCacheRef) {
+                        await cfCacheRef
+                            .then((cfCache) => cfCache
+                            .match(cacheKey)
+                            .then(async (cachedResponse) => {
+                            if (cachedResponse) {
+                                if (typeof logger === 'boolean') {
+                                    if (logger) {
+                                        await import('chalk')
+                                            .then(({ Chalk }) => {
+                                            const chalk = new Chalk({ level: 1 });
+                                            console.debug(chalk.green('CF Cache hit'), cacheKey.url);
+                                        })
+                                            .catch(() => console.debug('CF Cache hit', cacheKey.url));
+                                    }
+                                }
+                                else {
+                                    logger(`CF Cache hit ${cacheKey.url}`);
+                                }
+                                if (cachedResponse.status < 500) {
+                                    resolve(cachedResponse);
+                                }
+                                else {
+                                    void cfCache.delete(cacheKey).then(() => resolve(cachedResponse));
+                                }
+                            }
+                            else {
+                                if (typeof logger === 'boolean') {
+                                    if (logger) {
+                                        await import('chalk')
+                                            .then(({ Chalk }) => {
+                                            const chalk = new Chalk({ level: 1 });
+                                            console.warn(chalk.yellow('CF Cache missed'), cacheKey.url);
+                                        })
+                                            .catch(() => console.warn('CF Cache missed', cacheKey.url));
+                                    }
+                                }
+                                else {
+                                    logger(`CF Cache missed ${cacheKey.url}`);
+                                }
+                                await this.loggingFetch(info, init, undefined, logger)
+                                    .then((response) => {
+                                    resolve(response.clone());
+                                    return response;
+                                })
+                                    .then((response) => {
+                                    if (response.status < 500) {
+                                        response = new Response(response.body, response);
+                                        response.headers.set('Cache-Control', `s-maxage=${cacheTtl}`);
+                                        if (response.headers.has('ETag')) {
+                                            return cfCache.put(cacheKey, response).then(async () => {
+                                                if (typeof logger === 'boolean') {
+                                                    if (logger) {
+                                                        await import('chalk')
+                                                            .then(({ Chalk }) => {
+                                                            const chalk = new Chalk({ level: 1 });
+                                                            console.debug(chalk.gray('CF Cache saved'), cacheKey.url);
+                                                        })
+                                                            .catch(() => console.debug('CF Cache saved', cacheKey.url));
+                                                    }
+                                                }
+                                                else {
+                                                    logger(`CF Cache saved ${cacheKey.url}`);
+                                                }
+                                            });
+                                        }
+                                        else {
+                                            return (CryptoHelpers.generateETag(response)
+                                                .then((etag) => response.headers.set('ETag', etag))
+                                                // eslint-disable-next-line @typescript-eslint/no-misused-promises
+                                                .finally(() => cfCache.put(cacheKey, response).then(async () => {
+                                                if (typeof logger === 'boolean') {
+                                                    if (logger) {
+                                                        await import('chalk')
+                                                            .then(({ Chalk }) => {
+                                                            const chalk = new Chalk({ level: 1 });
+                                                            console.debug(chalk.gray('CF Cache saved'), cacheKey.url);
+                                                        })
+                                                            .catch(() => console.debug('CF Cache saved', cacheKey.url));
+                                                    }
+                                                }
+                                                else {
+                                                    logger(`CF Cache saved ${cacheKey.url}`);
+                                                }
+                                            })));
+                                        }
+                                    }
+                                    else {
+                                        return;
+                                    }
+                                });
+                            }
+                        })
+                            .catch(async (error) => {
+                            if (typeof logger === 'boolean') {
+                                if (logger) {
+                                    await import('chalk')
+                                        .then(({ Chalk }) => {
+                                        const chalk = new Chalk({ level: 1 });
+                                        console.error(chalk.red('CF Cache match error'), error);
+                                    })
+                                        .catch(() => console.error('CF Cache match error', error));
+                                }
+                            }
+                            else {
+                                logger(`CF Cache match error ${error}`);
+                            }
+                            resolve(this.loggingFetch(info, init, undefined, logger));
+                        }))
+                            .catch(async (error) => {
+                            if (typeof logger === 'boolean') {
+                                if (logger) {
+                                    await import('chalk')
+                                        .then(({ Chalk }) => {
+                                        const chalk = new Chalk({ level: 1 });
+                                        console.error(chalk.red('CF Cache open error'), error);
+                                    })
+                                        .catch(() => console.error('CF Cache open error', error));
+                                }
+                            }
+                            else {
+                                logger(`CF Cache open error ${error}`);
+                            }
+                            resolve(this.loggingFetch(info, init, undefined, logger));
+                        });
+                    }
+                    else {
+                        if (typeof logger === 'boolean') {
+                            if (logger) {
+                                await import('chalk')
+                                    .then(({ Chalk }) => {
+                                    const chalk = new Chalk({ level: 1 });
+                                    console.warn(chalk.yellow('CF Cache not available'));
+                                })
+                                    .catch(() => console.warn('CF Cache not available'));
+                            }
+                        }
+                        else {
+                            logger('CF Cache not available');
+                        }
+                        resolve(this.loggingFetch(info, init, undefined, logger));
+                    }
+                }
+                else {
+                    if (typeof logger === 'boolean') {
+                        if (logger) {
+                            await import('chalk')
+                                .then(({ Chalk }) => {
+                                const chalk = new Chalk({ level: 1 });
+                                console.warn(chalk.yellow('CF Cache ignored'), cacheKey.url);
+                            })
+                                .catch(() => console.warn('CF Cache ignored', cacheKey.url));
+                        }
+                    }
+                    else {
+                        logger(`CF Cache ignored ${cacheKey.url}`);
+                    }
+                    resolve(this.loggingFetch(info, init, undefined, logger));
+                }
+            }),
+        }));
+    }
+    static loggingFetch(info, init, body = false, logger = false) {
+        // eslint-disable-next-line @typescript-eslint/no-misused-promises
+        return new Promise((resolve, reject) => fetch(info, init)
+            .then(async (response) => {
+            resolve(response.clone());
+            // Allow mutable headers
+            response = new Response(response.body, response);
+            const loggingContent = {
+                headers: Object.fromEntries(this.stripSensitiveHeaders(response.headers).entries()),
+                status: response.status,
+                statusText: response.statusText,
+                ok: response.ok,
+                type: response.type,
+            };
+            if (body) {
+                if (response.headers.get('Content-Type')?.toLowerCase().startsWith('application/json')) {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                    loggingContent['body'] = await response.json();
+                }
+                else {
+                    loggingContent['body'] = await response.text();
+                }
+            }
+            if (typeof logger === 'boolean') {
+                if (logger) {
+                    await import('chalk')
+                        .then(({ Chalk }) => {
+                        const chalk = new Chalk({ level: 1 });
+                        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                        console.debug(response.ok ? chalk.green('Fetch response') : chalk.red('Fetch response'), response.ok, response.ok ? chalk.green(response.url || info.toString()) : chalk.red(response.url || info.toString()), JSON.stringify(loggingContent, null, '\t'));
+                    })
+                        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                        .catch(() => console.debug('Fetch response', response.ok, response.url || info.toString(), JSON.stringify(loggingContent, null, '\t')));
+                }
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                logger(`Fetch response ${response.ok} ${response.url || info.toString()} ${JSON.stringify(loggingContent, null, '\t')}`);
+            }
+        })
+            .catch(reject));
+    }
+    /**
+     * Parses the Server-Timing header and returns an object with the metrics.
+     * The object keys are the metric names (with optional descriptions), and the values are the duration of each metric or null if no duration is found.
+     *
+     * @param {string} [serverTimingHeader=''] - The Server-Timing header string.
+     * @returns {Record<string, number | null>} An object where keys are metric names (with optional descriptions) and values are the durations in milliseconds or null.
+     */
+    static serverTiming(serverTimingHeader = '') {
+        const result = {};
+        if (serverTimingHeader && serverTimingHeader.trim().length > 0) {
+            // Split the header by comma to get each metric
+            const metrics = serverTimingHeader.trim().split(',');
+            metrics.forEach((metric) => {
+                // Split each metric by semicolon to separate the name from other attributes
+                const parts = metric.split(';').map((part) => part.trim());
+                // Get the metric name
+                const name = parts[0];
+                // Find the 'dur' attribute and convert it to a number
+                const durationPart = parts.find((part) => part.startsWith('dur='));
+                const duration = durationPart ? parseFloat(durationPart.split('=')[1]) : null;
+                // Optionally find the 'desc' attribute
+                const descriptionPart = parts.find((part) => part.startsWith('desc='));
+                const description = descriptionPart ? descriptionPart.split('=')[1] : null;
+                // Construct the key name with optional description
+                const keyName = description ? `${name} (${description})` : name;
+                if (name) {
+                    result[keyName] = duration;
+                }
+            });
+        }
+        return result;
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@chainfuse/helpers",
+	"version": "0.0.2",
+	"description": "",
+	"author": "ChainFuse",
+	"homepage": "https://github.com/ChainFuse/packages/tree/main/packages/helpers#readme",
+	"license": "Apache-2.0",
+	"main": "./dist/index.mjs",
+	"directories": {
+		"lib": "dist",
+		"test": "__tests__"
+	},
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ChainFuse/packages.git"
+	},
+	"scripts": {
+		"fmt": "prettier --check .",
+		"fmt:fix": "prettier --write .",
+		"lint": "eslint .",
+		"lint:fix": "npm run lint -- --fix",
+		"build": "tsc",
+		"build:clean": "npm run build -- --build --clean && npm run build",
+		"pretest": "tsc --project tsconfig.tests.json",
+		"test": "node --enable-source-maps --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout",
+		"test:local": "npm run test"
+	},
+	"type": "module",
+	"bugs": {
+		"url": "https://github.com/ChainFuse/packages/issues"
+	},
+	"types": "./dist/index.d.mts",
+	"engines": {
+		"node": ">=20.16.0"
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.mjs",
+			"types": "./dist/index.d.mts"
+		}
+	},
+	"prettier": "@demosjarco/prettier-config",
+	"dependencies": {
+		"chalk": "^5.3.0",
+		"cloudflare": "^3.5.0",
+		"uuid": "^10.0.0"
+	},
+	"devDependencies": {
+		"@chainfuse/types": "^0.0.2",
+		"@types/node": "^22.5.1",
+		"@types/uuid": "^10.0.0"
+	},
+	"gitHead": "46683b9763bb38416cc19e46dda479814d6a4c14"
+}