@start9labs/start-sdk 0.4.0-beta.9 → 0.4.0

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,37 @@
-import * as matches from "ts-matches";
-import * as INI from "ini";
-import * as T from "../../../base/lib/types";
+import { type X2jOptions, type XmlBuilderOptions } from 'fast-xml-parser';
+import * as INI from 'ini';
+import { z } from 'zod';
+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 +90,93 @@ 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 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>;
+    /**
+     * Create a File Helper for an .xml file.
+     *
+     * Supports optional parser/builder options from `fast-xml-parser`.
      */
-    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 xml<A extends Record<string, unknown>>(path: ToPath, shape: Validator<Record<string, unknown>, A>, options?: {
+        parser?: X2jOptions;
+        builder?: XmlBuilderOptions;
+    }): FileHelper<A>;
+    static xml<A extends Transformed, Transformed = Record<string, unknown>>(path: ToPath, shape: Validator<Transformed, A>, options: {
+        parser?: X2jOptions;
+        builder?: XmlBuilderOptions;
+    }, transformers: Transformers<Record<string, unknown>, Transformed, A>): FileHelper<A>;
 }
 export default FileHelper;