@start9labs/start-sdk 0.3.6-alpha2 → 0.3.6-alpha4

package/cjs/lib/util/Overlay.d.ts

@@ -0,0 +1,57 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import * as T from "../types";
+import * as cp from "child_process";
+import { Buffer } from "node:buffer";
+export declare const execFile: typeof cp.execFile.__promisify__;
+export declare class Overlay {
+    readonly effects: T.Effects;
+    readonly imageId: T.ImageId;
+    readonly rootfs: string;
+    readonly guid: T.Guid;
+    private constructor();
+    static of(effects: T.Effects, image: {
+        id: T.ImageId;
+        sharedRun?: boolean;
+    }): Promise<Overlay>;
+    mount(options: MountOptions, path: string): Promise<Overlay>;
+    destroy(): Promise<void>;
+    exec(command: string[], options?: CommandOptions, timeoutMs?: number | null): Promise<{
+        exitCode: number | null;
+        exitSignal: NodeJS.Signals | null;
+        stdout: string | Buffer;
+        stderr: string | Buffer;
+    }>;
+    spawn(command: string[], options?: CommandOptions): Promise<cp.ChildProcessWithoutNullStreams>;
+}
+export type CommandOptions = {
+    env?: {
+        [variable: string]: string;
+    };
+    cwd?: string;
+    user?: string;
+};
+export type MountOptions = MountOptionsVolume | MountOptionsAssets | MountOptionsPointer | MountOptionsBackup;
+export type MountOptionsVolume = {
+    type: "volume";
+    id: string;
+    subpath: string | null;
+    readonly: boolean;
+};
+export type MountOptionsAssets = {
+    type: "assets";
+    id: string;
+    subpath: string | null;
+};
+export type MountOptionsPointer = {
+    type: "pointer";
+    packageId: string;
+    volumeId: string;
+    subpath: string | null;
+    readonly: boolean;
+};
+export type MountOptionsBackup = {
+    type: "backup";
+    subpath: string | null;
+};

package/cjs/lib/util/Overlay.js

@@ -0,0 +1,197 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Overlay = exports.execFile = void 0;
+const fs = __importStar(require("fs/promises"));
+const cp = __importStar(require("child_process"));
+const util_1 = require("util");
+const node_buffer_1 = require("node:buffer");
+exports.execFile = (0, util_1.promisify)(cp.execFile);
+const WORKDIR = (imageId) => `/media/startos/images/${imageId}/`;
+class Overlay {
+    constructor(effects, imageId, rootfs, guid) {
+        this.effects = effects;
+        this.imageId = imageId;
+        this.rootfs = rootfs;
+        this.guid = guid;
+    }
+    static async of(effects, image) {
+        const { id, sharedRun } = image;
+        const [rootfs, guid] = await effects.createOverlayedImage({
+            imageId: id,
+        });
+        const shared = ["dev", "sys", "proc"];
+        if (!!sharedRun) {
+            shared.push("run");
+        }
+        for (const dirPart of shared) {
+            await fs.mkdir(`${rootfs}/${dirPart}`, { recursive: true });
+            await (0, exports.execFile)("mount", [
+                "--rbind",
+                `/${dirPart}`,
+                `${rootfs}/${dirPart}`,
+            ]);
+        }
+        return new Overlay(effects, id, rootfs, guid);
+    }
+    async mount(options, path) {
+        path = path.startsWith("/")
+            ? `${this.rootfs}${path}`
+            : `${this.rootfs}/${path}`;
+        if (options.type === "volume") {
+            const subpath = options.subpath
+                ? options.subpath.startsWith("/")
+                    ? options.subpath
+                    : `/${options.subpath}`
+                : "/";
+            await (0, exports.execFile)("mount", [
+                "--bind",
+                `/media/startos/volumes/${options.id}${subpath}`,
+                path,
+            ]);
+        }
+        else if (options.type === "assets") {
+            const subpath = options.subpath
+                ? options.subpath.startsWith("/")
+                    ? options.subpath
+                    : `/${options.subpath}`
+                : "/";
+            await (0, exports.execFile)("mount", [
+                "--bind",
+                `/media/startos/assets/${options.id}${subpath}`,
+                path,
+            ]);
+        }
+        else if (options.type === "pointer") {
+            await this.effects.mount({ location: path, target: options });
+        }
+        else if (options.type === "backup") {
+            const subpath = options.subpath
+                ? options.subpath.startsWith("/")
+                    ? options.subpath
+                    : `/${options.subpath}`
+                : "/";
+            await (0, exports.execFile)("mount", [
+                "--bind",
+                `/media/startos/backup${subpath}`,
+                path,
+            ]);
+        }
+        else {
+            throw new Error(`unknown type ${options.type}`);
+        }
+        return this;
+    }
+    async destroy() {
+        const imageId = this.imageId;
+        const guid = this.guid;
+        await this.effects.destroyOverlayedImage({ guid });
+    }
+    async exec(command, options, timeoutMs = 30000) {
+        const imageMeta = await fs
+            .readFile(`/media/startos/images/${this.imageId}.json`, {
+            encoding: "utf8",
+        })
+            .catch(() => "{}")
+            .then(JSON.parse);
+        let extra = [];
+        if (options === null || options === void 0 ? void 0 : options.user) {
+            extra.push(`--user=${options.user}`);
+            delete options.user;
+        }
+        let workdir = imageMeta.workdir || "/";
+        if (options === null || options === void 0 ? void 0 : options.cwd) {
+            workdir = options.cwd;
+            delete options.cwd;
+        }
+        const child = cp.spawn("start-cli", [
+            "chroot",
+            `--env=/media/startos/images/${this.imageId}.env`,
+            `--workdir=${workdir}`,
+            ...extra,
+            this.rootfs,
+            ...command,
+        ], options || {});
+        const pid = child.pid;
+        const stdout = { data: "" };
+        const stderr = { data: "" };
+        const appendData = (appendTo) => (chunk) => {
+            if (typeof appendTo.data === "string" && typeof chunk === "string") {
+                appendTo.data += chunk;
+            }
+            else if (typeof chunk === "string" || chunk instanceof node_buffer_1.Buffer) {
+                appendTo.data = node_buffer_1.Buffer.concat([
+                    node_buffer_1.Buffer.from(appendTo.data),
+                    node_buffer_1.Buffer.from(chunk),
+                ]);
+            }
+            else {
+                console.error("received unexpected chunk", chunk);
+            }
+        };
+        return new Promise((resolve, reject) => {
+            child.on("error", reject);
+            if (timeoutMs !== null && pid) {
+                setTimeout(() => (0, exports.execFile)("pkill", ["-9", "-s", String(pid)]).catch((_) => { }), timeoutMs);
+            }
+            child.stdout.on("data", appendData(stdout));
+            child.stderr.on("data", appendData(stderr));
+            child.on("exit", (code, signal) => resolve({
+                exitCode: code,
+                exitSignal: signal,
+                stdout: stdout.data,
+                stderr: stderr.data,
+            }));
+        });
+    }
+    async spawn(command, options) {
+        const imageMeta = await fs
+            .readFile(`/media/startos/images/${this.imageId}.json`, {
+            encoding: "utf8",
+        })
+            .catch(() => "{}")
+            .then(JSON.parse);
+        let extra = [];
+        if (options === null || options === void 0 ? void 0 : options.user) {
+            extra.push(`--user=${options.user}`);
+            delete options.user;
+        }
+        let workdir = imageMeta.workdir || "/";
+        if (options === null || options === void 0 ? void 0 : options.cwd) {
+            workdir = options.cwd;
+            delete options.cwd;
+        }
+        return cp.spawn("start-cli", [
+            "chroot",
+            `--env=/media/startos/images/${this.imageId}.env`,
+            `--workdir=${workdir}`,
+            ...extra,
+            this.rootfs,
+            ...command,
+        ], options);
+    }
+}
+exports.Overlay = Overlay;
+//# sourceMappingURL=Overlay.js.map

package/cjs/lib/util/Overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Overlay.js","sourceRoot":"","sources":["../../../../lib/util/Overlay.ts"],"names":[],"mappings":"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"}

package/cjs/lib/util/deepEqual.d.ts

@@ -0,0 +1 @@
+export declare function deepEqual(...args: unknown[]): unknown;

package/cjs/lib/util/deepEqual.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepEqual = void 0;
+const ts_matches_1 = require("ts-matches");
+function deepEqual(...args) {
+    if (!ts_matches_1.object.test(args[args.length - 1]))
+        return args[args.length - 1];
+    const objects = args.filter(ts_matches_1.object.test);
+    if (objects.length === 0) {
+        for (const x of args)
+            if (x !== args[0])
+                return false;
+        return true;
+    }
+    if (objects.length !== args.length)
+        return false;
+    const allKeys = new Set(objects.flatMap((x) => Object.keys(x)));
+    for (const key of allKeys) {
+        for (const x of objects) {
+            if (!(key in x))
+                return false;
+            if (!deepEqual(objects[0][key], x[key]))
+                return false;
+        }
+    }
+    return true;
+}
+exports.deepEqual = deepEqual;
+//# sourceMappingURL=deepEqual.js.map

package/cjs/lib/util/deepEqual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepEqual.js","sourceRoot":"","sources":["../../../../lib/util/deepEqual.ts"],"names":[],"mappings":";;;AAAA,2CAAmC;AAEnC,SAAgB,SAAS,CAAC,GAAG,IAAe;IAC1C,IAAI,CAAC,mBAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACrE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,mBAAM,CAAC,IAAI,CAAC,CAAA;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE;QACxB,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;QACrD,OAAO,IAAI,CAAA;KACZ;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAChD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE;QACzB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE;YACvB,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;YAC7B,IAAI,CAAC,SAAS,CAAE,OAAO,CAAC,CAAC,CAAS,CAAC,GAAG,CAAC,EAAG,CAAS,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;SACxE;KACF;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAhBD,8BAgBC"}

package/cjs/lib/util/deepMerge.d.ts

@@ -0,0 +1 @@
+export declare function deepMerge(...args: unknown[]): unknown;

package/cjs/lib/util/deepMerge.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepMerge = void 0;
+const ts_matches_1 = require("ts-matches");
+function deepMerge(...args) {
+    const lastItem = args[args.length - 1];
+    if (!ts_matches_1.object.test(lastItem))
+        return lastItem;
+    const objects = args.filter(ts_matches_1.object.test).filter((x) => !Array.isArray(x));
+    if (objects.length === 0)
+        return lastItem;
+    if (objects.length === 1)
+        objects.unshift({});
+    const allKeys = new Set(objects.flatMap((x) => Object.keys(x)));
+    for (const key of allKeys) {
+        const filteredValues = objects.flatMap((x) => key in x ? [x[key]] : []);
+        objects[0][key] = deepMerge(...filteredValues);
+    }
+    return objects[0];
+}
+exports.deepMerge = deepMerge;
+//# sourceMappingURL=deepMerge.js.map

package/cjs/lib/util/deepMerge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepMerge.js","sourceRoot":"","sources":["../../../../lib/util/deepMerge.ts"],"names":[],"mappings":";;;AAAA,2CAAmC;AAEnC,SAAgB,SAAS,CAAC,GAAG,IAAe;IAC1C,MAAM,QAAQ,GAAI,IAAY,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC/C,IAAI,CAAC,mBAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAA;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,mBAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IACzE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAe,CAAA;IAChD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE;QACzB,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3C,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAE,CAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAClC,CACA;QAAC,OAAe,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,cAAc,CAAC,CAAA;KACzD;IACD,OAAO,OAAO,CAAC,CAAC,CAAQ,CAAA;AAC1B,CAAC;AAdD,8BAcC"}

package/cjs/lib/util/fileHelper.d.ts

@@ -0,0 +1,75 @@
+import * as matches from "ts-matches";
+import * as T from "../types";
+/**
+ * Used in the get config and the set config exported functions.
+ * The idea is that we are going to be reading/ writing to a file, or multiple files. And then we use this tool
+ * to keep the same path on the read and write, and have methods for helping with structured data.
+ * And if we are not using a structured data, we can use the raw method which forces the construction of a BiMap
+ * ```ts
+        import {InputSpec} from './InputSpec.ts'
+        import {matches, T} from '../deps.ts';
+        const { object, string, number, boolean, arrayOf, array, anyOf, allOf } = matches
+        const someValidator = object({
+        data: string
+        })
+        const jsonFile = FileHelper.json({
+        path: 'data.json',
+        validator: someValidator,
+        volume: 'main'
+        })
+        const  tomlFile = FileHelper.toml({
+        path: 'data.toml',
+        validator: someValidator,
+        volume: 'main'
+        })
+        const rawFile = FileHelper.raw({
+        path: 'data.amazingSettings',
+        volume: 'main'
+        fromData(dataIn: Data): string {
+            return `myDatais ///- ${dataIn.data}`
+        },
+        toData(rawData: string): Data {
+        const [,data] = /myDatais \/\/\/- (.*)/.match(rawData)
+        return {data}
+        }
+        })
+
+        export const setConfig : T.ExpectedExports.setConfig= async (effects, config) => {
+        await  jsonFile.write({ data: 'here lies data'}, effects)
+        }
+
+        export const getConfig: T.ExpectedExports.getConfig = async (effects, config) => ({
+        spec: InputSpec,
+        config: nullIfEmpty({
+            ...jsonFile.get(effects)
+        })
+    ```
+ */
+export declare class FileHelper<A> {
+    readonly path: string;
+    readonly writeData: (dataIn: A) => string;
+    readonly readData: (stringValue: string) => A;
+    protected constructor(path: string, writeData: (dataIn: A) => string, readData: (stringValue: string) => A);
+    write(data: A, effects: T.Effects): Promise<void>;
+    read(effects: T.Effects): Promise<A | null>;
+    merge(data: A, effects: T.Effects): Promise<void>;
+    /**
+     * Create a File Helper for an arbitrary file type.
+     *
+     * Provide custom functions for translating data to the file format and visa versa.
+     */
+    static raw<A>(path: string, toFile: (dataIn: A) => string, fromFile: (rawData: string) => A): FileHelper<A>;
+    /**
+     * Create a File Helper for a .json file
+     */
+    static json<A>(path: string, shape: matches.Validator<unknown, A>): FileHelper<A>;
+    /**
+     * Create a File Helper for a .toml file
+     */
+    static toml<A extends Record<string, unknown>>(path: string, shape: matches.Validator<unknown, A>): FileHelper<A>;
+    /**
+     * Create a File Helper for a .yaml file
+     */
+    static yaml<A extends Record<string, unknown>>(path: string, shape: matches.Validator<unknown, A>): FileHelper<A>;
+}
+export default FileHelper;

package/cjs/lib/util/fileHelper.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileHelper = void 0;
+const YAML = __importStar(require("yaml"));
+const TOML = __importStar(require("@iarna/toml"));
+const lodash_1 = __importDefault(require("lodash"));
+const fs = __importStar(require("node:fs/promises"));
+const previousPath = /(.+?)\/([^/]*)$/;
+/**
+ * Used in the get config and the set config exported functions.
+ * The idea is that we are going to be reading/ writing to a file, or multiple files. And then we use this tool
+ * to keep the same path on the read and write, and have methods for helping with structured data.
+ * And if we are not using a structured data, we can use the raw method which forces the construction of a BiMap
+ * ```ts
+        import {InputSpec} from './InputSpec.ts'
+        import {matches, T} from '../deps.ts';
+        const { object, string, number, boolean, arrayOf, array, anyOf, allOf } = matches
+        const someValidator = object({
+        data: string
+        })
+        const jsonFile = FileHelper.json({
+        path: 'data.json',
+        validator: someValidator,
+        volume: 'main'
+        })
+        const  tomlFile = FileHelper.toml({
+        path: 'data.toml',
+        validator: someValidator,
+        volume: 'main'
+        })
+        const rawFile = FileHelper.raw({
+        path: 'data.amazingSettings',
+        volume: 'main'
+        fromData(dataIn: Data): string {
+            return `myDatais ///- ${dataIn.data}`
+        },
+        toData(rawData: string): Data {
+        const [,data] = /myDatais \/\/\/- (.*)/.match(rawData)
+        return {data}
+        }
+        })
+
+        export const setConfig : T.ExpectedExports.setConfig= async (effects, config) => {
+        await  jsonFile.write({ data: 'here lies data'}, effects)
+        }
+
+        export const getConfig: T.ExpectedExports.getConfig = async (effects, config) => ({
+        spec: InputSpec,
+        config: nullIfEmpty({
+            ...jsonFile.get(effects)
+        })
+    ```
+ */
+class FileHelper {
+    constructor(path, writeData, readData) {
+        this.path = path;
+        this.writeData = writeData;
+        this.readData = readData;
+    }
+    async write(data, effects) {
+        const parent = previousPath.exec(this.path);
+        if (parent) {
+            await fs.mkdir(parent[1], { recursive: true });
+        }
+        await fs.writeFile(this.path, this.writeData(data));
+    }
+    async read(effects) {
+        if (!(await fs.access(this.path).then(() => true, () => false))) {
+            return null;
+        }
+        return this.readData(await fs.readFile(this.path).then((data) => data.toString("utf-8")));
+    }
+    async merge(data, effects) {
+        const fileData = (await this.read(effects).catch(() => ({}))) || {};
+        const mergeData = lodash_1.default.merge({}, fileData, data);
+        return await this.write(mergeData, effects);
+    }
+    /**
+     * Create a File Helper for an arbitrary file type.
+     *
+     * Provide custom functions for translating data to the file format and visa versa.
+     */
+    static raw(path, toFile, fromFile) {
+        return new FileHelper(path, toFile, fromFile);
+    }
+    /**
+     * Create a File Helper for a .json file
+     */
+    static json(path, shape) {
+        return new FileHelper(path, (inData) => {
+            return JSON.stringify(inData, null, 2);
+        }, (inString) => {
+            return shape.unsafeCast(JSON.parse(inString));
+        });
+    }
+    /**
+     * Create a File Helper for a .toml file
+     */
+    static toml(path, shape) {
+        return new FileHelper(path, (inData) => {
+            return TOML.stringify(inData);
+        }, (inString) => {
+            return shape.unsafeCast(TOML.parse(inString));
+        });
+    }
+    /**
+     * Create a File Helper for a .yaml file
+     */
+    static yaml(path, shape) {
+        return new FileHelper(path, (inData) => {
+            return YAML.stringify(inData, null, 2);
+        }, (inString) => {
+            return shape.unsafeCast(YAML.parse(inString));
+        });
+    }
+}
+exports.FileHelper = FileHelper;
+exports.default = FileHelper;
+//# sourceMappingURL=fileHelper.js.map

package/cjs/lib/util/fileHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileHelper.js","sourceRoot":"","sources":["../../../../lib/util/fileHelper.ts"],"names":[],"mappings":"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"}

package/cjs/lib/util/getDefaultString.d.ts

@@ -0,0 +1,2 @@
+import { DefaultString } from "../config/configTypes";
+export declare function getDefaultString(defaultSpec: DefaultString): string;

package/cjs/lib/util/getDefaultString.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultString = void 0;
+const getRandomString_1 = require("./getRandomString");
+function getDefaultString(defaultSpec) {
+    if (typeof defaultSpec === "string") {
+        return defaultSpec;
+    }
+    else {
+        return (0, getRandomString_1.getRandomString)(defaultSpec);
+    }
+}
+exports.getDefaultString = getDefaultString;
+//# sourceMappingURL=getDefaultString.js.map

package/cjs/lib/util/getDefaultString.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getDefaultString.js","sourceRoot":"","sources":["../../../../lib/util/getDefaultString.ts"],"names":[],"mappings":";;;AACA,uDAAmD;AAEnD,SAAgB,gBAAgB,CAAC,WAA0B;IACzD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE;QACnC,OAAO,WAAW,CAAA;KACnB;SAAM;QACL,OAAO,IAAA,iCAAe,EAAC,WAAW,CAAC,CAAA;KACpC;AACH,CAAC;AAND,4CAMC"}

package/cjs/lib/util/getRandomCharInSet.d.ts

@@ -0,0 +1 @@
+export declare function getRandomCharInSet(charset: string): string;