@start9labs/start-sdk 0.4.0-beta.6 → 0.4.0-beta.61

package/package/lib/util/Volume.d.ts

@@ -0,0 +1,48 @@
+import * as fs from 'node:fs/promises';
+import * as T from '../../../base/lib/types';
+/**
+ * Common interface for objects that have a subpath method (Volume, SubContainer, etc.)
+ */
+export interface PathBase {
+    subpath(path: string): string;
+}
+/**
+ * @description Represents a volume in the StartOS filesystem.
+ * Provides utilities for reading and writing files within the volume.
+ */
+export declare class Volume<Id extends string = string> implements PathBase {
+    readonly id: Id;
+    /**
+     * The absolute path to this volume's root directory
+     */
+    readonly path: string;
+    constructor(id: Id);
+    /**
+     * Get the absolute path to a file or directory within this volume
+     * @param subpath Path relative to the volume root
+     */
+    subpath(subpath: string): string;
+    /**
+     * @description Read a file from this volume
+     * @param subpath Path relative to the volume root (e.g. "config.json" or "/data/file.txt")
+     * @param options Optional read options (same as node:fs/promises readFile)
+     */
+    readFile(subpath: string, options?: Parameters<typeof fs.readFile>[1]): Promise<Buffer | string>;
+    /**
+     * @description Write a file to this volume
+     * @param subpath Path relative to the volume root (e.g. "config.json" or "/data/file.txt")
+     * @param data The data to write
+     * @param options Optional write options (same as node:fs/promises writeFile)
+     */
+    writeFile(subpath: string, data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView>, options?: Parameters<typeof fs.writeFile>[2]): Promise<void>;
+}
+/**
+ * Type-safe volumes object that provides Volume instances for each volume defined in the manifest
+ */
+export type Volumes<Manifest extends T.SDKManifest> = {
+    [K in Manifest['volumes'][number]]: Volume<K>;
+};
+/**
+ * Creates a type-safe volumes object from a manifest
+ */
+export declare function createVolumes<Manifest extends T.SDKManifest>(manifest: Manifest): Volumes<Manifest>;

package/package/lib/util/Volume.js

@@ -0,0 +1,91 @@
+"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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Volume = void 0;
+exports.createVolumes = createVolumes;
+const fs = __importStar(require("node:fs/promises"));
+/**
+ * @description Represents a volume in the StartOS filesystem.
+ * Provides utilities for reading and writing files within the volume.
+ */
+class Volume {
+    constructor(id) {
+        this.id = id;
+        this.path = `/media/startos/volumes/${id}`;
+    }
+    /**
+     * Get the absolute path to a file or directory within this volume
+     * @param subpath Path relative to the volume root
+     */
+    subpath(subpath) {
+        return subpath.startsWith('/')
+            ? `${this.path}${subpath}`
+            : `${this.path}/${subpath}`;
+    }
+    /**
+     * @description Read a file from this volume
+     * @param subpath Path relative to the volume root (e.g. "config.json" or "/data/file.txt")
+     * @param options Optional read options (same as node:fs/promises readFile)
+     */
+    async readFile(subpath, options) {
+        const fullPath = this.subpath(subpath);
+        return fs.readFile(fullPath, options);
+    }
+    /**
+     * @description Write a file to this volume
+     * @param subpath Path relative to the volume root (e.g. "config.json" or "/data/file.txt")
+     * @param data The data to write
+     * @param options Optional write options (same as node:fs/promises writeFile)
+     */
+    async writeFile(subpath, data, options) {
+        const fullPath = this.subpath(subpath);
+        const dir = fullPath.replace(/\/[^/]*\/?$/, '');
+        await fs.mkdir(dir, { recursive: true });
+        return fs.writeFile(fullPath, data, options);
+    }
+}
+exports.Volume = Volume;
+/**
+ * Creates a type-safe volumes object from a manifest
+ */
+function createVolumes(manifest) {
+    const volumes = {};
+    for (const volumeId of manifest.volumes) {
+        ;
+        volumes[volumeId] = new Volume(volumeId);
+    }
+    return volumes;
+}
+//# sourceMappingURL=Volume.js.map

package/package/lib/util/Volume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Volume.js","sourceRoot":"","sources":["../../../../package/lib/util/Volume.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+EA,sCAQC;AAvFD,qDAAsC;AAUtC;;;GAGG;AACH,MAAa,MAAM;IAMjB,YAAqB,EAAM;QAAN,OAAE,GAAF,EAAE,CAAI;QACzB,IAAI,CAAC,IAAI,GAAG,0BAA0B,EAAE,EAAE,CAAA;IAC5C,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,OAAe;QACrB,OAAO,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAC5B,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE;YAC1B,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,EAAE,CAAA;IAC/B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CACZ,OAAe,EACf,OAA2C;QAE3C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACtC,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACvC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CACb,OAAe,EACf,IAIkD,EAClD,OAA4C;QAE5C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA;QAC/C,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACxC,OAAO,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;CACF;AArDD,wBAqDC;AASD;;GAEG;AACH,SAAgB,aAAa,CAC3B,QAAkB;IAElB,MAAM,OAAO,GAAG,EAAuB,CAAA;IACvC,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACxC,CAAC;QAAC,OAAe,CAAC,QAAQ,CAAC,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

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

@@ -1,6 +1,36 @@
-import * as matches from "ts-matches";
-import * as INI from "ini";
-import * as T from "../../../base/lib/types";
+import { z } from 'zod';
+import * as INI from 'ini';
+import * as T from '../../../base/lib/types';
+import { PathBase } from './Volume';
+/**
+ * Bidirectional transformers for converting between the raw file format and
+ * the application-level data type. Used with FileHelper factory methods.
+ *
+ * @typeParam Raw - The native type the file format parses to (e.g. `Record<string, unknown>` for JSON)
+ * @typeParam Transformed - The application-level type after transformation
+ */
+export type Transformers<Raw = unknown, Transformed = unknown, Validated extends Transformed = Transformed> = {
+    /** Transform raw parsed data into the application type */
+    onRead: (value: Raw) => Transformed;
+    /** Transform application data back into the raw format for writing */
+    onWrite: (value: Validated) => Raw;
+};
+type ToPath = string | {
+    base: PathBase;
+    subpath: string;
+};
+type Validator<_T, U> = z.ZodType<U>;
+type ReadType<A> = {
+    once: () => Promise<A | null>;
+    const: (effects: T.Effects) => Promise<A | null>;
+    watch: (effects: T.Effects, abort?: AbortSignal) => AsyncGenerator<A | null, never, unknown>;
+    onChange: (effects: T.Effects, callback: (value: A | null, error?: Error) => {
+        cancel: boolean;
+    } | Promise<{
+        cancel: boolean;
+    }>) => void;
+    waitFor: (effects: T.Effects, pred: (value: A | null) => boolean) => Promise<A | null>;
+};
 /**
  * @description Use this class to read/write an underlying configuration file belonging to the upstream service.
  *
@@ -59,47 +89,80 @@ export declare class FileHelper<A> {
      * Reads the file from disk and converts it to structured data.
      */
     private readOnce;
-    private readConst;
-    private readWatch;
-    private readOnChange;
-    get read(): {
-        once: () => Promise<A | null>;
-        const: (effects: T.Effects) => Promise<A | null>;
-        watch: (effects: T.Effects) => AsyncGenerator<Awaited<A> | null, null, unknown>;
-        onChange: (effects: T.Effects, callback: (value: A | null, error?: Error) => void | Promise<void>) => void;
-    };
+    private createFileWatchable;
+    /**
+     * Create a reactive reader for this file.
+     *
+     * Returns an object with multiple read strategies:
+     * - `once()` - Read the file once and return the parsed value
+     * - `const(effects)` - Read once but re-read when the file changes (for use with constRetry)
+     * - `watch(effects)` - Async generator yielding new values on each file change
+     * - `onChange(effects, callback)` - Fire a callback on each file change
+     * - `waitFor(effects, predicate)` - Block until the file value satisfies a predicate
+     *
+     * @param map - Optional transform function applied after validation
+     * @param eq - Optional equality function to deduplicate watch emissions
+     */
+    read(): ReadType<A>;
+    read<B>(map: (value: A) => B, eq?: (left: B | null, right: B | null) => boolean): ReadType<B>;
     /**
      * Accepts full structured data and overwrites the existing file on disk if it exists.
      */
-    write(effects: T.Effects, data: A): Promise<null>;
+    write(effects: T.Effects, data: T.AllowReadonly<A> | A, options?: {
+        allowWriteAfterConst?: boolean;
+    }): Promise<null>;
     /**
      * Accepts partial structured data and performs a merge with the existing file on disk.
      */
-    merge(effects: T.Effects, data: T.DeepPartial<A>): Promise<null>;
+    merge(effects: T.Effects, data: T.AllowReadonly<T.DeepPartial<A>>, options?: {
+        allowWriteAfterConst?: boolean;
+    }): Promise<null>;
     /**
      * We wanted to be able to have a fileHelper, and just modify the path later in time.
      * Like one behavior of another dependency or something similar.
      */
-    withPath(path: string): FileHelper<A>;
+    withPath(path: ToPath): FileHelper<A>;
     /**
      * Create a File Helper for an arbitrary file type.
      *
      * Provide custom functions for translating data to/from the file format.
      */
-    static raw<A>(path: string, toFile: (dataIn: A) => string, fromFile: (rawData: string) => unknown, validate: (data: unknown) => A): FileHelper<A>;
+    static raw<A>(path: ToPath, toFile: (dataIn: A) => string, fromFile: (rawData: string) => unknown, validate: (data: unknown) => A): FileHelper<A>;
+    private static rawTransformed;
+    /**
+     * Create a File Helper for a text file
+     */
+    static string(path: ToPath): FileHelper<string>;
+    static string<A extends string>(path: ToPath, shape: Validator<string, A>): FileHelper<A>;
+    static string<A extends Transformed, Transformed = string>(path: ToPath, shape: Validator<Transformed, A>, transformers: Transformers<string, Transformed, A>): FileHelper<A>;
     /**
      * Create a File Helper for a .json file.
      */
-    static json<A>(path: string, shape: matches.Validator<unknown, A>): FileHelper<A>;
+    static json<A>(path: ToPath, shape: Validator<unknown, A>): FileHelper<A>;
+    static json<A extends Transformed, Transformed = unknown>(path: ToPath, shape: Validator<unknown, A>, transformers: Transformers<unknown, Transformed, A>): FileHelper<A>;
+    /**
+     * Create a File Helper for a .yaml file
+     */
+    static yaml<A extends Record<string, unknown>>(path: ToPath, shape: Validator<Record<string, unknown>, A>): FileHelper<A>;
+    static yaml<A extends Transformed, Transformed = Record<string, unknown>>(path: ToPath, shape: Validator<Transformed, A>, transformers: Transformers<Record<string, unknown>, Transformed, 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>;
+    static toml<A extends Record<string, unknown>>(path: ToPath, shape: Validator<Record<string, unknown>, A>): FileHelper<A>;
+    static toml<A extends Transformed, Transformed = Record<string, unknown>>(path: ToPath, shape: Validator<Transformed, A>, transformers: Transformers<Record<string, unknown>, Transformed, A>): FileHelper<A>;
     /**
-     * Create a File Helper for a .yaml file
+     * Create a File Helper for a .ini file.
+     *
+     * Supports optional encode/decode options and custom transformers.
+     */
+    static ini<A extends Record<string, unknown>>(path: ToPath, shape: Validator<Record<string, unknown>, A>, options?: INI.EncodeOptions & INI.DecodeOptions): FileHelper<A>;
+    static ini<A extends Transformed, Transformed = Record<string, unknown>>(path: ToPath, shape: Validator<Transformed, A>, options: INI.EncodeOptions & INI.DecodeOptions, transformers: Transformers<Record<string, unknown>, Transformed, A>): FileHelper<A>;
+    /**
+     * Create a File Helper for a .env file (KEY=VALUE format, one per line).
+     *
+     * Lines starting with `#` are treated as comments and ignored on read.
      */
-    static yaml<A extends Record<string, unknown>>(path: string, shape: matches.Validator<unknown, A>): FileHelper<A>;
-    static ini<A extends Record<string, unknown>>(path: string, shape: matches.Validator<unknown, A>, options?: INI.EncodeOptions & INI.DecodeOptions): FileHelper<A>;
-    static env<A extends Record<string, string>>(path: string, shape: matches.Validator<unknown, A>): FileHelper<A>;
+    static env<A extends Record<string, string>>(path: ToPath, shape: Validator<Record<string, string>, A>): FileHelper<A>;
+    static env<A extends Transformed, Transformed = Record<string, string>>(path: ToPath, shape: Validator<Transformed, A>, transformers: Transformers<Record<string, string>, Transformed, A>): FileHelper<A>;
 }
 export default FileHelper;

package/package/lib/util/fileHelper.js

@@ -34,34 +34,40 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileHelper = void 0;
+const zod_1 = require("zod");
 const YAML = __importStar(require("yaml"));
 const TOML = __importStar(require("@iarna/toml"));
 const INI = __importStar(require("ini"));
 const fs = __importStar(require("node:fs/promises"));
 const util_1 = require("../../../base/lib/util");
+const Watchable_1 = require("../../../base/lib/util/Watchable");
 const previousPath = /(.+?)\/([^/]*)$/;
 const exists = (path) => fs.access(path).then(() => true, () => false);
 async function onCreated(path) {
-    if (path === "/")
+    if (path === '/')
         return;
-    if (!path.startsWith("/"))
+    if (!path.startsWith('/'))
         path = `${process.cwd()}/${path}`;
     if (await exists(path)) {
         return;
     }
-    const split = path.split("/");
+    const split = path.split('/');
     const filename = split.pop();
-    const parent = split.join("/");
+    const parent = split.join('/');
     await onCreated(parent);
     const ctrl = new AbortController();
     const watch = fs.watch(parent, { persistent: false, signal: ctrl.signal });
+    if (await exists(path)) {
+        ctrl.abort();
+        return;
+    }
     if (await fs.access(path).then(() => true, () => false)) {
-        ctrl.abort("finished");
+        ctrl.abort();
         return;
     }
     for await (let event of watch) {
         if (event.filename === filename) {
-            ctrl.abort("finished");
+            ctrl.abort('finished');
             return;
         }
     }
@@ -71,8 +77,10 @@ function fileMerge(...args) {
     for (const arg of args) {
         if (res === arg)
             continue;
-        else if (typeof res === "object" &&
-            typeof arg === "object" &&
+        else if (res &&
+            arg &&
+            typeof res === 'object' &&
+            typeof arg === 'object' &&
             !Array.isArray(res) &&
             !Array.isArray(arg)) {
             for (const key of Object.keys(arg)) {
@@ -84,6 +92,26 @@ function fileMerge(...args) {
     }
     return res;
 }
+function filterUndefined(a) {
+    if (a && typeof a === 'object') {
+        if (Array.isArray(a)) {
+            return a.map(filterUndefined);
+        }
+        return Object.entries(a).reduce((acc, [k, v]) => {
+            if (v !== undefined) {
+                acc[k] = filterUndefined(v);
+            }
+            return acc;
+        }, {});
+    }
+    return a;
+}
+function toPath(path) {
+    if (typeof path === 'string') {
+        return path;
+    }
+    return path.base.subpath(path.subpath);
+}
 /**
  * @description Use this class to read/write an underlying configuration file belonging to the upstream service.
  *
@@ -150,7 +178,7 @@ class FileHelper {
         if (!(await exists(this.path))) {
             return null;
         }
-        return await fs.readFile(this.path).then((data) => data.toString("utf-8"));
+        return await fs.readFile(this.path).then((data) => data.toString('utf-8'));
     }
     async readFile() {
         const raw = await this.readFileRaw();
@@ -162,89 +190,107 @@ class FileHelper {
     /**
      * Reads the file from disk and converts it to structured data.
      */
-    async readOnce() {
+    async readOnce(map) {
         const data = await this.readFile();
         if (!data)
             return null;
-        return this.validate(data);
+        return map(this.validate(data));
     }
-    async readConst(effects) {
-        const watch = this.readWatch(effects);
-        const res = await watch.next();
-        if (effects.constRetry) {
-            if (!this.consts.includes(effects.constRetry))
-                this.consts.push(effects.constRetry);
-            watch.next().then(() => {
-                this.consts = this.consts.filter((a) => a === effects.constRetry);
-                effects.constRetry && effects.constRetry();
-            });
-        }
-        return res.value;
-    }
-    async *readWatch(effects) {
-        let res;
-        while (effects.isInContext) {
-            if (await exists(this.path)) {
-                const ctrl = new AbortController();
-                const watch = fs.watch(this.path, {
-                    persistent: false,
-                    signal: ctrl.signal,
-                });
-                res = await this.readOnce();
-                const listen = Promise.resolve()
-                    .then(async () => {
-                    for await (const _ of watch) {
-                        ctrl.abort("finished");
-                        return null;
-                    }
-                })
-                    .catch((e) => console.error((0, util_1.asError)(e)));
-                yield res;
-                await listen;
+    createFileWatchable(effects, map, eq) {
+        const doRead = async () => {
+            const data = await this.readFile();
+            if (!data)
+                return null;
+            return this.validate(data);
+        };
+        const filePath = this.path;
+        const fileHelper = this;
+        const wrappedMap = (raw) => {
+            if (raw === null)
+                return null;
+            return map(raw);
+        };
+        return new (class extends Watchable_1.Watchable {
+            constructor() {
+                super(...arguments);
+                this.label = 'FileHelper';
             }
-            else {
-                yield null;
-                await onCreated(this.path).catch((e) => console.error((0, util_1.asError)(e)));
+            async fetch() {
+                return doRead();
             }
-        }
-        return null;
-    }
-    readOnChange(effects, callback) {
-        ;
-        (async () => {
-            for await (const value of this.readWatch(effects)) {
-                try {
-                    await callback(value);
-                }
-                catch (e) {
-                    console.error("callback function threw an error @ FileHelper.read.onChange", e);
+            async *produce(abort) {
+                while (this.effects.isInContext && !abort.aborted) {
+                    if (await exists(filePath)) {
+                        const ctrl = new AbortController();
+                        abort.addEventListener('abort', () => ctrl.abort());
+                        const watch = fs.watch(filePath, {
+                            persistent: false,
+                            signal: ctrl.signal,
+                        });
+                        yield await doRead();
+                        await Promise.resolve()
+                            .then(async () => {
+                            for await (const _ of watch) {
+                                ctrl.abort();
+                                return null;
+                            }
+                        })
+                            .catch((e) => console.error((0, util_1.asError)(e)));
+                    }
+                    else {
+                        yield null;
+                        await onCreated(filePath).catch((e) => console.error((0, util_1.asError)(e)));
+                    }
                 }
             }
-        })()
-            .catch((e) => callback(null, e))
-            .catch((e) => console.error("callback function threw an error @ FileHelper.read.onChange", e));
+            onConstRegistered(value) {
+                if (!this.effects.constRetry)
+                    return;
+                const record = [
+                    this.effects.constRetry,
+                    value,
+                    wrappedMap,
+                    eq,
+                ];
+                fileHelper.consts.push(record);
+                return () => {
+                    fileHelper.consts = fileHelper.consts.filter((r) => r !== record);
+                };
+            }
+        })(effects, { map: wrappedMap, eq });
     }
-    get read() {
+    read(map, eq) {
+        map = map ?? ((a) => a);
+        eq = eq ?? util_1.deepEqual;
         return {
-            once: () => this.readOnce(),
-            const: (effects) => this.readConst(effects),
-            watch: (effects) => this.readWatch(effects),
-            onChange: (effects, callback) => this.readOnChange(effects, callback),
+            once: () => this.readOnce(map),
+            const: (effects) => this.createFileWatchable(effects, map, eq).const(),
+            watch: (effects, abort) => this.createFileWatchable(effects, map, eq).watch(abort),
+            onChange: (effects, callback) => this.createFileWatchable(effects, map, eq).onChange(callback),
+            waitFor: (effects, pred) => this.createFileWatchable(effects, map, eq).waitFor(pred),
         };
     }
     /**
      * Accepts full structured data and overwrites the existing file on disk if it exists.
      */
-    async write(effects, data) {
-        await this.writeFile(this.validate(data));
-        if (effects.constRetry && this.consts.includes(effects.constRetry))
-            throw new Error(`Canceled: write after const: ${this.path}`);
+    async write(effects, data, options = {}) {
+        const newData = this.validate(data);
+        await this.writeFile(newData);
+        if (!options.allowWriteAfterConst && effects.constRetry) {
+            const records = this.consts.filter(([c]) => c === effects.constRetry);
+            for (const record of records) {
+                const [_, prev, map, eq] = record;
+                if (!eq(prev, map(newData))) {
+                    throw new Error(`Canceled: write after const: ${this.path}`);
+                }
+            }
+        }
         return null;
     }
     /**
      * Accepts partial structured data and performs a merge with the existing file on disk.
      */
-    async merge(effects, data) {
+    async merge(effects, data, options = {}) {
         const fileDataRaw = await this.readFileRaw();
         let fileData = fileDataRaw === null ? null : this.readData(fileDataRaw);
         try {
@@ -255,12 +301,14 @@ class FileHelper {
         const toWrite = this.writeData(mergeData);
         if (toWrite !== fileDataRaw) {
             this.writeFile(mergeData);
-            if (effects.constRetry && this.consts.includes(effects.constRetry)) {
-                const diff = (0, util_1.partialDiff)(fileData, mergeData);
-                if (!diff) {
-                    return null;
+            if (!options.allowWriteAfterConst && effects.constRetry) {
+                const records = this.consts.filter(([c]) => c === effects.constRetry);
+                for (const record of records) {
+                    const [_, prev, map, eq] = record;
+                    if (!eq(prev, map(mergeData))) {
+                        throw new Error(`Canceled: write after const: ${this.path}`);
+                    }
                 }
-                throw new Error(`Canceled: write after const: ${this.path}`);
             }
         }
         return null;
@@ -270,7 +318,7 @@ class FileHelper {
      * Like one behavior of another dependency or something similar.
      */
     withPath(path) {
-        return new FileHelper(path, this.writeData, this.readData, this.validate);
+        return new FileHelper(toPath(path), this.writeData, this.readData, this.validate);
     }
     /**
      * Create a File Helper for an arbitrary file type.
@@ -278,37 +326,47 @@ class FileHelper {
      * Provide custom functions for translating data to/from the file format.
      */
     static raw(path, toFile, fromFile, validate) {
-        return new FileHelper(path, toFile, fromFile, validate);
+        return new FileHelper(toPath(path), toFile, fromFile, validate);
     }
-    /**
-     * Create a File Helper for a .json file.
-     */
-    static json(path, shape) {
-        return new FileHelper(path, (inData) => JSON.stringify(inData, null, 2), (inString) => JSON.parse(inString), (data) => shape.unsafeCast(data));
+    static rawTransformed(path, toFile, fromFile, validate, transformers) {
+        return FileHelper.raw(path, (inData) => {
+            if (transformers) {
+                return toFile(transformers.onWrite(inData));
+            }
+            return toFile(inData);
+        }, (fileData) => {
+            if (transformers) {
+                return transformers.onRead(fromFile(fileData));
+            }
+            return fromFile(fileData);
+        }, validate);
     }
-    /**
-     * Create a File Helper for a .toml file
-     */
-    static toml(path, shape) {
-        return new FileHelper(path, (inData) => TOML.stringify(inData), (inString) => TOML.parse(inString), (data) => shape.unsafeCast(data));
+    static string(path, shape, transformers) {
+        return FileHelper.rawTransformed(path, (inData) => inData, (inString) => inString, (data) => (shape || zod_1.z.string()).parse(data), transformers);
     }
-    /**
-     * Create a File Helper for a .yaml file
-     */
-    static yaml(path, shape) {
-        return new FileHelper(path, (inData) => YAML.stringify(inData, null, 2), (inString) => YAML.parse(inString), (data) => shape.unsafeCast(data));
+    static json(path, shape, transformers) {
+        return FileHelper.rawTransformed(path, (inData) => JSON.stringify(inData, null, 2), (inString) => JSON.parse(inString), (data) => shape.parse(data), transformers);
+    }
+    static yaml(path, shape, transformers) {
+        return FileHelper.rawTransformed(path, (inData) => YAML.stringify(inData, null, 2), (inString) => YAML.parse(inString), (data) => shape.parse(data), transformers);
+    }
+    static toml(path, shape, transformers) {
+        return FileHelper.rawTransformed(path, (inData) => TOML.stringify(inData), (inString) => TOML.parse(inString), (data) => shape.parse(data), transformers);
     }
-    static ini(path, shape, options) {
-        return new FileHelper(path, (inData) => INI.stringify(inData, options), (inString) => INI.parse(inString, options), (data) => shape.unsafeCast(data));
+    static ini(path, shape, options, transformers) {
+        return FileHelper.rawTransformed(path, (inData) => INI.stringify(filterUndefined(inData), options), (inString) => INI.parse(inString, options), (data) => shape.parse(data), transformers);
     }
-    static env(path, shape) {
-        return new FileHelper(path, (inData) => Object.entries(inData)
+    static env(path, shape, transformers) {
+        return FileHelper.rawTransformed(path, (inData) => Object.entries(inData)
             .map(([k, v]) => `${k}=${v}`)
-            .join("\n"), (inString) => Object.fromEntries(inString
-            .split("\n")
+            .join('\n'), (inString) => Object.fromEntries(inString
+            .split('\n')
             .map((line) => line.trim())
-            .filter((line) => !line.startsWith("#") && line.includes("="))
-            .map((line) => line.split("=", 2))), (data) => shape.unsafeCast(data));
+            .filter((line) => !line.startsWith('#') && line.includes('='))
+            .map((line) => {
+            const pos = line.indexOf('=');
+            return [line.slice(0, pos), line.slice(pos + 1)];
+        })), (data) => shape.parse(data), transformers);
     }
 }
 exports.FileHelper = FileHelper;