@bouko/fs 0.0.1

package/dist/definitions/math.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export declare const RangeSchema: z.ZodObject<{
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+}, z.core.$strip>;

package/dist/definitions/math.js

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export const RangeSchema = z.object({
+    min: z.number().int(),
+    max: z.number().int()
+});

package/dist/functions/file.d.ts

@@ -0,0 +1,25 @@
+import { EnsureFileOptions } from "../types/file";
+export declare function ensureFile(filePath: string, options?: EnsureFileOptions): Promise<void>;
+export declare function readJson<T>(filePath: string, fallback?: object): Promise<T>;
+type SpecialFile = {
+    buffer: ArrayBuffer;
+    last_modified: Date;
+};
+type Mp3File = SpecialFile & {
+    duration: number;
+    metadata: {
+        title: string;
+        artwork: string | null;
+        artists: string[];
+    };
+};
+type FileReturnMap = {
+    json: SpecialFile;
+    mp3: Mp3File;
+};
+type FileKind = keyof FileReturnMap;
+type InferKind<P extends string> = P extends `${string}.mp3` ? "mp3" : P extends `${string}.json` ? "json" : never;
+export declare function readFile<P extends string>(filePath: P, options?: EnsureFileOptions): Promise<FileReturnMap[InferKind<P>]>;
+export declare function readFile<T extends FileKind>(filePath: string, options?: EnsureFileOptions): Promise<FileReturnMap[T]>;
+export declare function saveFile(filePath: string, options: EnsureFileOptions): Promise<void>;
+export {};

package/dist/functions/file.js

@@ -0,0 +1,86 @@
+import fs from "fs/promises";
+import path from "path";
+import * as mm from "music-metadata";
+import { sanitizeArrayMap } from "@bouko/ts";
+export async function ensureFile(filePath, options) {
+    const dirPath = path.dirname(filePath);
+    await fs.mkdir(dirPath, { recursive: true });
+    let contents = null;
+    let encoding = "utf8";
+    if (options?.data) {
+        switch (options.type) {
+            case "json":
+                contents =
+                    JSON.stringify(options.data, null, options.pretty === false ? undefined : 2) + "\n";
+                break;
+            case "text":
+                contents = options.data;
+                break;
+            case "buffer":
+                if (!options.data)
+                    throw new Error("Not found");
+                contents = options.data;
+                encoding = undefined;
+                break;
+        }
+    }
+    try {
+        if (options && contents)
+            await fs.writeFile(filePath, contents, {
+                encoding,
+                flag: "wx",
+            });
+        else
+            await fs.readFile(filePath);
+    }
+    catch (err) {
+        if (err.code !== "EEXIST") {
+            throw err;
+        }
+    }
+}
+export async function readJson(filePath, fallback) {
+    await ensureFile(filePath, {
+        type: "json",
+        data: fallback || {}
+    });
+    const raw = await fs.readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return sanitizeArrayMap(parsed);
+}
+export async function readFile(filePath, options) {
+    await ensureFile(filePath, options);
+    const fileType = filePath.split(".")[1];
+    const { mtime: last_modified } = await fs.stat(filePath);
+    if (fileType === "json") {
+        const raw = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        const sanitized = sanitizeArrayMap(parsed);
+        const buffer = await fs.readFile(filePath);
+        return {
+            buffer: buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+            last_modified
+        };
+    }
+    if (fileType === "mp3") {
+        const buffer = await fs.readFile(filePath);
+        const { common, format } = await mm.parseFile(filePath, { duration: true });
+        const pic = common.picture?.[0] ?? null;
+        return {
+            buffer: buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+            metadata: {
+                title: common.title ?? path.basename(filePath),
+                artists: common.artists ?? (common.artist ? [common.artist] : []),
+                artwork: pic ? `data:${pic.format};base64,${Buffer.from(pic.data).toString("base64")}` : null
+            },
+            duration: format.duration ?? 0,
+            last_modified
+        };
+    }
+    throw new Error(`Unsupported file type: ${filePath}`);
+}
+export async function saveFile(filePath, options) {
+    const dirPath = path.dirname(filePath);
+    await fs.mkdir(dirPath, { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(options.data, null, 2), "utf8");
+}

package/dist/functions/folder.d.ts

@@ -0,0 +1,12 @@
+export declare const createFolder: (folderPath: string) => Promise<string | undefined>;
+export declare const fetchFiles: ({ folderPath, ext, page, pageSize }: {
+    folderPath: string;
+    ext: string;
+    page: number;
+    pageSize: number;
+}) => Promise<{
+    items: string[];
+    page: number;
+    totalItems: number;
+    totalPages: number;
+}>;

package/dist/functions/folder.js

@@ -0,0 +1,22 @@
+import fs from "fs/promises";
+import path from "path";
+import { byName } from "@bouko/ts";
+export const createFolder = (folderPath) => fs.mkdir(folderPath, { recursive: true });
+export const fetchFiles = async ({ folderPath, ext, page, pageSize }) => {
+    const entries = await fs.readdir(folderPath, { withFileTypes: true });
+    const filePaths = entries
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith("." + ext))
+        .map((e) => path.join(folderPath, e.name))
+        .sort(byName);
+    const totalItems = filePaths.length;
+    const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
+    const safePage = Math.min(Math.max(page, 0), totalPages - 1);
+    const start = safePage * pageSize;
+    console.log(filePaths.slice(start, start + pageSize));
+    return {
+        items: filePaths.slice(start, start + pageSize),
+        page: safePage,
+        totalItems,
+        totalPages
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./functions/folder";
+export * from "./functions/file";
+export * from "./types/file";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./functions/folder";
+export * from "./functions/file";
+export * from "./types/file";

package/dist/types/file.d.ts

@@ -0,0 +1,11 @@
+export type EnsureFileOptions = {
+    type: "json";
+    data: object;
+    pretty?: boolean;
+} | {
+    type: "text";
+    data: string;
+} | {
+    type: "buffer";
+    data?: Uint8Array;
+};

package/dist/types/file.js

@@ -0,0 +1 @@
+export {};

package/dist/types/generic.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Type definitions for common data structures.
+ *
+ * - `StringMap`: Map of string keys to string values.
+ * - `JsonMap`: Object of primitives, arrays, or nested maps.
+ * - `JsonValue`: Union type representing a valid JSON value.
+ *
+ * They are intended to facilitate type-safe handling
+ * of generic objects (ex. forms).
+**/
+export type StringMap<T = string> = Record<string, T>;
+export type ArrayMap<T = string> = Record<string, T[]>;
+export type JsonMap = {
+    [key: string]: JsonValue | JsonValue[];
+};
+export type JsonValue = string | number | boolean | null | undefined | JsonMap | JsonValue[];
+export type PageQuery = {
+    page: number;
+    pageSize: number;
+    refresh?: boolean;
+};
+export type Page<T> = {
+    page: number;
+    items: T[];
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+};

package/dist/types/generic.js

@@ -0,0 +1,12 @@
+/**
+ * Type definitions for common data structures.
+ *
+ * - `StringMap`: Map of string keys to string values.
+ * - `JsonMap`: Object of primitives, arrays, or nested maps.
+ * - `JsonValue`: Union type representing a valid JSON value.
+ *
+ * They are intended to facilitate type-safe handling
+ * of generic objects (ex. forms).
+**/
+export {};
+// 

package/dist/types/math.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Type definitions for math/numbers.
+ *
+ * - `Range`: Object with `min` and `max` properties.
+ *
+ * They are intended to facilitate math utilities
+ * such as clamping, normalization, etc.
+**/
+export type Range = {
+    id?: string;
+    min: number;
+    max: number;
+};

package/dist/types/math.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for math/numbers.
+ *
+ * - `Range`: Object with `min` and `max` properties.
+ *
+ * They are intended to facilitate math utilities
+ * such as clamping, normalization, etc.
+**/
+export {};
+// clean

package/dist/types/work.d.ts

@@ -0,0 +1,3 @@
+export type Job = {
+    job_id: string;
+};

package/dist/types/work.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/checkers.d.ts

@@ -0,0 +1,2 @@
+export declare const isNum: (x: string) => boolean;
+export declare const isBool: (x: string) => boolean;

package/dist/utils/checkers.js

@@ -0,0 +1,5 @@
+export const isNum = (x) => !isNaN(Number(x));
+export const isBool = (x) => {
+    const lower = x.trim().toLowerCase();
+    return lower === "true" || lower === "false";
+};

package/dist/utils/converters.d.ts

@@ -0,0 +1,21 @@
+export declare function bufferToData(uint8: Uint8Array, mimetype?: string): string;
+export declare function bufferToData(uint8: Uint8Array | undefined, mimetype?: string): string | undefined;
+export declare function base64ToBuffer(base64: string): Uint8Array;
+export declare function base64ToFile(data: string, opts?: {
+    name?: string;
+    type?: string;
+}): File;
+export declare function base64ToFile(data: undefined, opts?: {
+    name?: string;
+    type?: string;
+}): undefined;
+export declare function base64ToFile(data: string | undefined, opts?: {
+    name?: string;
+    type?: string;
+}): File | undefined;
+export declare function dataToFile(data: string, opts?: {
+    name?: string;
+}): File;
+export declare function dataToFile(data: string | undefined, opts?: {
+    name?: string;
+}): File | undefined;

package/dist/utils/converters.js

@@ -0,0 +1,48 @@
+export function bufferToData(uint8, mimetype) {
+    if (!uint8)
+        return;
+    const len = uint8.byteLength;
+    let binary = "";
+    for (let i = 0; i < len; i++)
+        binary += String.fromCharCode(uint8[i]);
+    const decoded = btoa(binary);
+    if (mimetype)
+        return `data:${mimetype};base64,${decoded}`;
+    return decoded;
+}
+export function base64ToBuffer(base64) {
+    const binaryString = atob(base64); // decode base64 into binary string
+    const len = binaryString.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}
+export function base64ToFile(data, opts = {}) {
+    if (!data)
+        return;
+    const { name, type } = opts;
+    const byteArray = Uint8Array.from(atob(data), c => c.charCodeAt(0));
+    return new File([byteArray], name || "file", { type });
+}
+export function dataToFile(data, opts) {
+    if (!data)
+        return;
+    // If the data is in "data:[mime];base64,..." format, extract it
+    const matches = data.match(/^data:(.*?);base64,(.*)$/);
+    let mime;
+    let base64Data;
+    if (matches) {
+        mime = matches[1];
+        base64Data = matches[2];
+    }
+    else {
+        // If not a full data URI, just assume it's raw base64 without metadata
+        base64Data = data;
+    }
+    const byteArray = Uint8Array.from(atob(base64Data), c => c.charCodeAt(0));
+    return new File([byteArray], opts?.name || "file", {
+        type: mime || "application/octet-stream",
+    });
+}

package/dist/utils/env.d.ts

@@ -0,0 +1,5 @@
+export declare function getEnv(key: string): string;
+export declare function getEnv(key: string, fallback: string): string;
+export declare function getEnv(key: string, fallback: number): number;
+export declare function getEnv(key: string, fallback: boolean): boolean;
+export declare function getEnv<T>(key: string): T;

package/dist/utils/env.js

@@ -0,0 +1,23 @@
+import { parseStr } from "./parsers";
+/**
+ * Retrieves and parses an environment variable.
+ *
+ * @param key - The variable name
+ * @param fallback - Backup if no value is found (optional)
+ *
+ * @returns {JsonValue} The value parsed based on whichever
+ * primitive type the string matches.
+ *
+ * @throws {Error} If the variable is not found in the
+ * environment and there is no fallback set.
+**/
+export function getEnv(key, fallback) {
+    const raw = process.env[key];
+    if (!raw || raw === "") {
+        if (fallback !== undefined)
+            return fallback;
+        throw new Error(`ENV Missing: '${key}'`);
+    }
+    return parseStr(raw);
+}
+// clean

package/dist/utils/formatters.d.ts

@@ -0,0 +1,10 @@
+export declare const shortenStr: (str: string) => string;
+export declare const shortenNum: (x: number) => string;
+export declare const cleanStr: (str: string) => string;
+export declare const stripStr: (str: string, noise: string[]) => string;
+export type CanonicalTermsMap = Record<string, string[]>;
+export declare function getCanonicalMatch(input: string, map: CanonicalTermsMap): {
+    canonical: string;
+    matchedTerm: string;
+} | undefined;
+export declare function removeAll(input: string, needle: string, flags?: string): string;

package/dist/utils/formatters.js

@@ -0,0 +1,38 @@
+export const shortenStr = (str) => {
+    if (str.length <= 6)
+        return str;
+    return `${str.slice(0, 3)}...${str.slice(-3)}`;
+};
+export const shortenNum = (x) => {
+    if (x < 1000)
+        return x.toString();
+    if (x < 1_000_000)
+        return `${Math.floor(x / 1000)}k`;
+    return `${Math.floor(x / 1_000_000)}m`;
+};
+export const cleanStr = (str) => str
+    .trim()
+    .replace(/^[^\w(]+/g, "") // leading junk
+    .replace(/[^\w!?.)]+$/g, "") // trailing junk
+    .replace(/\s+/g, " ") // collapse spaces
+    .trim();
+export const stripStr = (str, noise) => {
+    for (const word of noise)
+        str = str.replace(new RegExp(word, "gi"), "");
+    return cleanStr(str.replace("()", ""));
+};
+export function getCanonicalMatch(input, map) {
+    const lower = input.toLowerCase();
+    for (const [canonical, terms] of Object.entries(map)) {
+        const searchTerms = [canonical, ...(terms ?? [])].filter(Boolean);
+        const match = searchTerms.find(t => lower.includes(t.toLowerCase()));
+        if (match)
+            return { canonical, matchedTerm: match };
+    }
+}
+export function removeAll(input, needle, flags = "gi") {
+    return needle ? input.replace(new RegExp(escapeRegExp(needle), flags), "") : input;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/utils/log.d.ts

@@ -0,0 +1,4 @@
+type Logger = (...messages: string[]) => void;
+type Config = Record<string, Logger>;
+export declare const log: Config;
+export {};

package/dist/utils/log.js

@@ -0,0 +1,5 @@
+import chalk from "chalk";
+export const log = {
+    info: (...msgs) => console.warn(chalk.blue.bold("[INFO]", ...msgs)),
+    error: (...msgs) => console.error(chalk.red.bold("[ERROR]", ...msgs))
+};

package/dist/utils/parsers.d.ts

@@ -0,0 +1,11 @@
+import { JsonValue } from "../types/generic";
+/**
+ * Parses a string value into it's appropriate
+ * type, or at least cleans up the string.
+ *
+ * @param {string} input - The text to parse.
+ *
+ * @returns {JsonValue} The value parsed based on whichever
+ * primitive type the string matches.
+**/
+export declare const parseStr: (input: string) => JsonValue;

package/dist/utils/parsers.js

@@ -0,0 +1,23 @@
+/**
+ * Parses a string value into it's appropriate
+ * type, or at least cleans up the string.
+ *
+ * @param {string} input - The text to parse.
+ *
+ * @returns {JsonValue} The value parsed based on whichever
+ * primitive type the string matches.
+**/
+export const parseStr = (input) => {
+    const trimmed = input.trim();
+    if (/^-?\d+(\.\d+)?$/.test(trimmed) && !isNaN(Number(trimmed)))
+        return Number(trimmed);
+    if (/^(true|false)$/i.test(trimmed))
+        return trimmed.toLowerCase() === "true";
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+};
+// clean

package/dist/utils/sorters.d.ts

@@ -0,0 +1 @@
+export declare const byName: (a: string, b: string) => number;

package/dist/utils/sorters.js

@@ -0,0 +1 @@
+export const byName = (a, b) => a.localeCompare(b, undefined, { sensitivity: "base" });

package/dist/utils/time.d.ts

@@ -0,0 +1,6 @@
+export declare function mmSS(timestamp: number): string;
+export declare const secToMs: (sec: number) => number;
+export declare function isoToMs(duration: string): number;
+export declare const sleep: (ms: number) => Promise<unknown>;
+export declare const isExpired: (date: Date | string) => boolean;
+export declare const fromNow: (ms: number) => Date;

package/dist/utils/time.js

@@ -0,0 +1,36 @@
+export function mmSS(timestamp) {
+    const totalSeconds = Math.floor(timestamp / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    const padSeconds = (n) => n.toString().padStart(2, "0");
+    return `${minutes}:${padSeconds(seconds)}`;
+}
+export const secToMs = (sec) => {
+    const converted = sec * 1000;
+    return Math.floor(converted);
+};
+export function isoToMs(duration) {
+    const regex = /P(?:([\d.]+)Y)?(?:([\d.]+)M)?(?:([\d.]+)W)?(?:([\d.]+)D)?(?:T(?:([\d.]+)H)?(?:([\d.]+)M)?(?:([\d.]+)S)?)?/;
+    const matches = duration.match(regex);
+    if (!matches)
+        return 0;
+    const [, years, months, weeks, days, hours, minutes, seconds] = matches;
+    // Approximate conversions for years/months if needed
+    const ms = (parseFloat(years || "0") * 365 * 24 * 60 * 60 +
+        parseFloat(months || "0") * 30 * 24 * 60 * 60 +
+        parseFloat(weeks || "0") * 7 * 24 * 60 * 60 +
+        parseFloat(days || "0") * 24 * 60 * 60 +
+        parseFloat(hours || "0") * 60 * 60 +
+        parseFloat(minutes || "0") * 60 +
+        parseFloat(seconds || "0")) * 1000;
+    return ms;
+}
+export const sleep = (ms) => {
+    return new Promise((res) => setTimeout(res, ms));
+};
+export const isExpired = (date) => {
+    if (typeof date === "string")
+        date = new Date(date);
+    return new Date() > date;
+};
+export const fromNow = (ms) => new Date(Date.now() + ms);

package/package.json

@@ -0,0 +1,58 @@
+{
+
+  "name": "@bouko/fs",
+
+  "version": "0.0.1",
+
+  "main": "./dist/index.js",
+
+  "types": "./dist/index.d.ts",
+
+  "license": "MIT",
+
+  "files": [
+
+    "dist"
+
+  ],
+
+  "publishConfig": {
+
+    "access": "public"
+
+  },
+
+  "author": "",
+
+  "description": "",
+
+  "engines": {},
+
+  "scripts": {
+
+    "build": "tsc"
+
+  },
+
+  "dependencies": {
+
+    "@bouko/ts": "^0.4.7",
+
+    "fs": "^0.0.1-security",
+
+    "music-metadata": "^11.12.1",
+
+    "path": "^0.12.7"
+
+  },
+
+  "devDependencies": {
+
+    "@types/node": "^24.3.0",
+
+    "typescript": "^5.9.2"
+
+  }
+
+}
+