@elaraai/east-node-std 0.0.1-beta.0

package/dist/fs.d.ts

@@ -0,0 +1,520 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { StringType, NullType, BooleanType, ArrayType, BlobType } from "@elaraai/east";
+import type { PlatformFunction, PlatformFunctionDef } from "@elaraai/east/internal";
+/**
+ * Reads a file as a UTF-8 string.
+ *
+ * Reads the entire contents of a file synchronously and decodes it as UTF-8 text.
+ * Paths are resolved relative to the current working directory.
+ *
+ * This is a platform function for the East language, enabling file reading
+ * in East programs running on Node.js.
+ *
+ * @param path - The file path to read (relative or absolute)
+ * @returns The file contents as a UTF-8 string
+ *
+ * @throws {EastError} When file cannot be read:
+ * - File doesn't exist: `ENOENT: no such file or directory`
+ * - No read permission: `EACCES: permission denied`
+ * - Path is a directory: `EISDIR: illegal operation on a directory`
+ *
+ * @example
+ * ```ts
+ * const readConfig = East.function([], StringType, $ => {
+ *     const content = $.let(FileSystem.readFile("config.txt"));
+ *     return content;
+ * });
+ * ```
+ */
+export declare const fs_read_file: PlatformFunctionDef<[typeof StringType], typeof StringType>;
+/**
+ * Writes a string to a file (overwrites existing content).
+ *
+ * Writes string content to a file synchronously, creating the file if it doesn't exist
+ * and overwriting it if it does. Content is encoded as UTF-8.
+ *
+ * This is a platform function for the East language, enabling file writing
+ * in East programs running on Node.js.
+ *
+ * @param path - The file path to write (relative or absolute)
+ * @param content - The string content to write (UTF-8 encoded)
+ * @returns Null
+ *
+ * @throws {EastError} When file cannot be written:
+ * - No write permission: `EACCES: permission denied`
+ * - Parent directory doesn't exist: `ENOENT: no such file or directory`
+ * - Path is a directory: `EISDIR: illegal operation on a directory`
+ *
+ * @example
+ * ```ts
+ * const saveOutput = East.function([], NullType, $ => {
+ *     $(FileSystem.writeFile("output.txt", "Hello, World!"));
+ * });
+ * ```
+ */
+export declare const fs_write_file: PlatformFunctionDef<[typeof StringType, typeof StringType], typeof NullType>;
+/**
+ * Appends a string to a file.
+ *
+ * Appends string content to the end of a file synchronously, creating the file
+ * if it doesn't exist. Content is encoded as UTF-8.
+ *
+ * This is a platform function for the East language, enabling file appending
+ * in East programs running on Node.js.
+ *
+ * @param path - The file path to append to (relative or absolute)
+ * @param content - The string content to append (UTF-8 encoded)
+ * @returns Null
+ *
+ * @throws {EastError} When file cannot be appended:
+ * - No write permission: `EACCES: permission denied`
+ * - Path is a directory: `EISDIR: illegal operation on a directory`
+ *
+ * @example
+ * ```ts
+ * const appendLog = East.function([], NullType, $ => {
+ *     $(FileSystem.appendFile("log.txt", "New log entry\n"));
+ * });
+ * ```
+ */
+export declare const fs_append_file: PlatformFunctionDef<[typeof StringType, typeof StringType], typeof NullType>;
+/**
+ * Deletes a file from the file system.
+ *
+ * Removes a file synchronously. If the file doesn't exist, an error is thrown.
+ * This operation cannot be undone.
+ *
+ * This is a platform function for the East language, enabling file deletion
+ * in East programs running on Node.js.
+ *
+ * @param path - The file path to delete (relative or absolute)
+ * @returns Null
+ *
+ * @throws {EastError} When file cannot be deleted:
+ * - File doesn't exist: `ENOENT: no such file or directory`
+ * - No delete permission: `EACCES: permission denied`
+ * - Path is a directory: `EISDIR: illegal operation on a directory`
+ *
+ * @example
+ * ```ts
+ * const cleanup = East.function([], NullType, $ => {
+ *     $(FileSystem.deleteFile("temp.txt"));
+ * });
+ * ```
+ */
+export declare const fs_delete_file: PlatformFunctionDef<[typeof StringType], typeof NullType>;
+/**
+ * Checks if a file or directory exists at the given path.
+ *
+ * Tests whether a path exists in the file system, returning true if it exists
+ * (whether file or directory) and false otherwise. This check is synchronous
+ * and does not throw errors for permission issues.
+ *
+ * This is a platform function for the East language, enabling path existence checks
+ * in East programs running on Node.js.
+ *
+ * @param path - The path to check (relative or absolute)
+ * @returns True if the path exists, false otherwise
+ *
+ * @example
+ * ```ts
+ * const checkConfig = East.function([], BooleanType, $ => {
+ *     return FileSystem.exists("config.txt");
+ * });
+ * ```
+ */
+export declare const fs_exists: PlatformFunctionDef<[typeof StringType], typeof BooleanType>;
+/**
+ * Checks if a path exists and is a regular file.
+ *
+ * Tests whether a path exists and is a regular file (not a directory, symlink, etc.).
+ * Returns false if the path doesn't exist or is not a file. Does not throw errors
+ * for permission issues.
+ *
+ * This is a platform function for the East language, enabling file type checks
+ * in East programs running on Node.js.
+ *
+ * @param path - The path to check (relative or absolute)
+ * @returns True if the path exists and is a file, false otherwise
+ *
+ * @example
+ * ```ts
+ * const checkIsFile = East.function([], BooleanType, $ => {
+ *     return FileSystem.isFile("data.json");
+ * });
+ * ```
+ */
+export declare const fs_is_file: PlatformFunctionDef<[typeof StringType], typeof BooleanType>;
+/**
+ * Checks if a path exists and is a directory.
+ *
+ * Tests whether a path exists and is a directory (not a regular file).
+ * Returns false if the path doesn't exist or is not a directory. Does not throw
+ * errors for permission issues.
+ *
+ * This is a platform function for the East language, enabling directory type checks
+ * in East programs running on Node.js.
+ *
+ * @param path - The path to check (relative or absolute)
+ * @returns True if the path exists and is a directory, false otherwise
+ *
+ * @example
+ * ```ts
+ * const checkIsDir = East.function([], BooleanType, $ => {
+ *     return FileSystem.isDirectory("src");
+ * });
+ * ```
+ */
+export declare const fs_is_directory: PlatformFunctionDef<[typeof StringType], typeof BooleanType>;
+/**
+ * Creates a directory, including any necessary parent directories.
+ *
+ * Creates a directory synchronously with recursive creation enabled, meaning
+ * all necessary parent directories will be created if they don't exist.
+ * If the directory already exists, no error is thrown.
+ *
+ * This is a platform function for the East language, enabling directory creation
+ * in East programs running on Node.js.
+ *
+ * @param path - The directory path to create (relative or absolute)
+ * @returns Null
+ *
+ * @throws {EastError} When directory cannot be created:
+ * - No write permission: `EACCES: permission denied`
+ * - Path exists as a file: `EEXIST: file already exists`
+ *
+ * @example
+ * ```ts
+ * const setupDirs = East.function([], NullType, $ => {
+ *     $(FileSystem.createDirectory("output/reports/2024"));
+ * });
+ * ```
+ */
+export declare const fs_create_directory: PlatformFunctionDef<[typeof StringType], typeof NullType>;
+/**
+ * Lists the names of all files and directories within a directory.
+ *
+ * Reads the contents of a directory synchronously and returns an array of entry names
+ * (not full paths). The entries include both files and subdirectories. Special entries
+ * like "." and ".." are not included. The order is not guaranteed.
+ *
+ * This is a platform function for the East language, enabling directory listing
+ * in East programs running on Node.js.
+ *
+ * @param path - The directory path to read (relative or absolute)
+ * @returns Array of file and directory names within the directory
+ *
+ * @throws {EastError} When directory cannot be read:
+ * - Directory doesn't exist: `ENOENT: no such file or directory`
+ * - No read permission: `EACCES: permission denied`
+ * - Path is not a directory: `ENOTDIR: not a directory`
+ *
+ * @example
+ * ```ts
+ * const listFiles = East.function([], ArrayType(StringType), $ => {
+ *     return FileSystem.readDirectory("src");
+ *     // Returns: ["index.ts", "utils", "types.ts"]
+ * });
+ * ```
+ */
+export declare const fs_read_directory: PlatformFunctionDef<[typeof StringType], ReturnType<typeof ArrayType<typeof StringType>>>;
+/**
+ * Reads a file as binary data without any encoding.
+ *
+ * Reads the entire contents of a file synchronously as raw bytes, returning
+ * a Blob (Uint8Array) without any text decoding. Useful for reading non-text
+ * files like images, PDFs, or binary data formats.
+ *
+ * This is a platform function for the East language, enabling binary file reading
+ * in East programs running on Node.js.
+ *
+ * @param path - The file path to read (relative or absolute)
+ * @returns The file contents as a Blob (binary data)
+ *
+ * @throws {EastError} When file cannot be read:
+ * - File doesn't exist: `ENOENT: no such file or directory`
+ * - No read permission: `EACCES: permission denied`
+ * - Path is a directory: `EISDIR: illegal operation on a directory`
+ *
+ * @example
+ * ```ts
+ * const loadImage = East.function([], BlobType, $ => {
+ *     return FileSystem.readFileBytes("logo.png");
+ * });
+ * ```
+ */
+export declare const fs_read_file_bytes: PlatformFunctionDef<[StringType], BlobType>;
+/**
+ * Writes binary data to a file (overwrites existing content).
+ *
+ * Writes raw binary data to a file synchronously without any text encoding,
+ * creating the file if it doesn't exist and overwriting it if it does.
+ * Useful for writing non-text files like images, PDFs, or binary data formats.
+ *
+ * This is a platform function for the East language, enabling binary file writing
+ * in East programs running on Node.js.
+ *
+ * @param path - The file path to write (relative or absolute)
+ * @param content - The binary content to write (Blob/Uint8Array)
+ * @returns Null
+ *
+ * @throws {EastError} When file cannot be written:
+ * - No write permission: `EACCES: permission denied`
+ * - Parent directory doesn't exist: `ENOENT: no such file or directory`
+ * - Path is a directory: `EISDIR: illegal operation on a directory`
+ *
+ * @example
+ * ```ts
+ * const saveBinary = East.function([BlobType], NullType, ($, data) => {
+ *     $(FileSystem.writeFileBytes("output.bin", data));
+ * });
+ * ```
+ */
+export declare const fs_write_file_bytes: PlatformFunctionDef<[typeof StringType, typeof BlobType], typeof NullType>;
+/**
+ * Node.js implementation of file system platform functions.
+ *
+ * Pass this array to {@link East.compile} to enable file system operations.
+ */
+declare const FileSystemImpl: PlatformFunction[];
+/**
+ * Grouped file system platform functions.
+ *
+ * Provides file system operations for East programs.
+ *
+ * @example
+ * ```ts
+ * import { East, NullType } from "@elaraai/east";
+ * import { FileSystem } from "@elaraai/east-node-std";
+ *
+ * const processFile = East.function([], NullType, $ => {
+ *     const content = $.let(FileSystem.readFile("input.txt"));
+ *     $(FileSystem.writeFile("output.txt", content));
+ * });
+ *
+ * const compiled = East.compile(processFile.toIR(), FileSystem.Implementation);
+ * await compiled();
+ * ```
+ */
+export declare const FileSystem: {
+    /**
+     * Reads a file as a UTF-8 string.
+     *
+     * Reads the entire contents of a file synchronously and decodes it as UTF-8 text.
+     * Paths are resolved relative to the current working directory.
+     *
+     * @param path - The file path to read (relative or absolute)
+     * @returns The file contents as a UTF-8 string
+     * @throws {EastError} When file cannot be read (ENOENT, EACCES, EISDIR)
+     *
+     * @example
+     * ```ts
+     * const readConfig = East.function([], StringType, $ => {
+     *     const content = $.let(FileSystem.readFile("config.txt"));
+     *     return content;
+     * });
+     *
+     * const compiled = East.compile(readConfig.toIR(), FileSystem.Implementation);
+     * await compiled();  // Returns file content as string
+     * ```
+     */
+    readonly readFile: PlatformFunctionDef<[StringType], StringType>;
+    /**
+     * Writes a string to a file (overwrites existing content).
+     *
+     * Writes string content to a file synchronously, creating the file if it doesn't exist
+     * and overwriting it if it does. Content is encoded as UTF-8.
+     *
+     * @param path - The file path to write (relative or absolute)
+     * @param content - The string content to write (UTF-8 encoded)
+     * @returns Null
+     * @throws {EastError} When file cannot be written (EACCES, ENOENT, EISDIR)
+     *
+     * @example
+     * ```ts
+     * const saveOutput = East.function([], NullType, $ => {
+     *     $(FileSystem.writeFile("output.txt", "Hello, World!"));
+     * });
+     *
+     * const compiled = East.compile(saveOutput.toIR(), FileSystem.Implementation);
+     * await compiled();  // File written successfully
+     * ```
+     */
+    readonly writeFile: PlatformFunctionDef<[StringType, StringType], NullType>;
+    /**
+     * Appends a string to a file.
+     *
+     * Appends string content to the end of a file synchronously, creating the file
+     * if it doesn't exist. Content is encoded as UTF-8.
+     *
+     * @param path - The file path to append to (relative or absolute)
+     * @param content - The string content to append (UTF-8 encoded)
+     * @returns Null
+     * @throws {EastError} When file cannot be appended (EACCES, EISDIR)
+     *
+     * @example
+     * ```ts
+     * const appendLog = East.function([], NullType, $ => {
+     *     $(FileSystem.appendFile("log.txt", "New log entry\n"));
+     * });
+     * ```
+     */
+    readonly appendFile: PlatformFunctionDef<[StringType, StringType], NullType>;
+    /**
+     * Deletes a file from the file system.
+     *
+     * Removes a file synchronously. If the file doesn't exist, an error is thrown.
+     * This operation cannot be undone.
+     *
+     * @param path - The file path to delete (relative or absolute)
+     * @returns Null
+     * @throws {EastError} When file cannot be deleted (ENOENT, EACCES, EISDIR)
+     *
+     * @example
+     * ```ts
+     * const cleanup = East.function([], NullType, $ => {
+     *     $(FileSystem.deleteFile("temp.txt"));
+     * });
+     * ```
+     */
+    readonly deleteFile: PlatformFunctionDef<[StringType], NullType>;
+    /**
+     * Checks if a file or directory exists at the given path.
+     *
+     * Tests whether a path exists in the file system, returning true if it exists
+     * (whether file or directory) and false otherwise.
+     *
+     * @param path - The path to check (relative or absolute)
+     * @returns True if the path exists, false otherwise
+     *
+     * @example
+     * ```ts
+     * const checkConfig = East.function([], BooleanType, $ => {
+     *     return FileSystem.exists("config.txt");
+     * });
+     * ```
+     */
+    readonly exists: PlatformFunctionDef<[StringType], BooleanType>;
+    /**
+     * Checks if a path exists and is a regular file.
+     *
+     * Tests whether a path exists and is a regular file (not a directory, symlink, etc.).
+     * Returns false if the path doesn't exist or is not a file.
+     *
+     * @param path - The path to check (relative or absolute)
+     * @returns True if the path exists and is a file, false otherwise
+     *
+     * @example
+     * ```ts
+     * const checkIsFile = East.function([], BooleanType, $ => {
+     *     return FileSystem.isFile("data.json");
+     * });
+     * ```
+     */
+    readonly isFile: PlatformFunctionDef<[StringType], BooleanType>;
+    /**
+     * Checks if a path exists and is a directory.
+     *
+     * Tests whether a path exists and is a directory (not a regular file).
+     * Returns false if the path doesn't exist or is not a directory.
+     *
+     * @param path - The path to check (relative or absolute)
+     * @returns True if the path exists and is a directory, false otherwise
+     *
+     * @example
+     * ```ts
+     * const checkIsDir = East.function([], BooleanType, $ => {
+     *     return FileSystem.isDirectory("src");
+     * });
+     * ```
+     */
+    readonly isDirectory: PlatformFunctionDef<[StringType], BooleanType>;
+    /**
+     * Creates a directory, including any necessary parent directories.
+     *
+     * Creates a directory synchronously with recursive creation enabled, meaning
+     * all necessary parent directories will be created if they don't exist.
+     *
+     * @param path - The directory path to create (relative or absolute)
+     * @returns Null
+     * @throws {EastError} When directory cannot be created (EACCES, EEXIST)
+     *
+     * @example
+     * ```ts
+     * const setupDirs = East.function([], NullType, $ => {
+     *     $(FileSystem.createDirectory("output/reports/2024"));
+     * });
+     * ```
+     */
+    readonly createDirectory: PlatformFunctionDef<[StringType], NullType>;
+    /**
+     * Lists the names of all files and directories within a directory.
+     *
+     * Reads the contents of a directory synchronously and returns an array of entry names
+     * (not full paths). The entries include both files and subdirectories.
+     *
+     * @param path - The directory path to read (relative or absolute)
+     * @returns Array of file and directory names within the directory
+     * @throws {EastError} When directory cannot be read (ENOENT, EACCES, ENOTDIR)
+     *
+     * @example
+     * ```ts
+     * const listFiles = East.function([], ArrayType(StringType), $ => {
+     *     return FileSystem.readDirectory("src");
+     * });
+     * ```
+     */
+    readonly readDirectory: PlatformFunctionDef<[StringType], ArrayType<StringType>>;
+    /**
+     * Reads a file as binary data without any encoding.
+     *
+     * Reads the entire contents of a file synchronously as raw bytes, returning
+     * a Blob (Uint8Array) without any text decoding.
+     *
+     * @param path - The file path to read (relative or absolute)
+     * @returns The file contents as a Blob (binary data)
+     * @throws {EastError} When file cannot be read (ENOENT, EACCES, EISDIR)
+     *
+     * @example
+     * ```ts
+     * const loadImage = East.function([], BlobType, $ => {
+     *     return FileSystem.readFileBytes("logo.png");
+     * });
+     * ```
+     */
+    readonly readFileBytes: PlatformFunctionDef<[StringType], BlobType>;
+    /**
+     * Writes binary data to a file (overwrites existing content).
+     *
+     * Writes raw binary data to a file synchronously without any text encoding,
+     * creating the file if it doesn't exist and overwriting it if it does.
+     *
+     * @param path - The file path to write (relative or absolute)
+     * @param content - The binary content to write (Blob/Uint8Array)
+     * @returns Null
+     * @throws {EastError} When file cannot be written (EACCES, ENOENT, EISDIR)
+     *
+     * @example
+     * ```ts
+     * const saveBinary = East.function([BlobType], NullType, ($, data) => {
+     *     $(FileSystem.writeFileBytes("output.bin", data));
+     * });
+     *
+     * const compiled = East.compile(saveBinary.toIR(), FileSystem.Implementation);
+     * const binaryData = new Uint8Array([1, 2, 3, 4]);
+     * await compiled(binaryData);  // Binary data written to file
+     * ```
+     */
+    readonly writeFileBytes: PlatformFunctionDef<[StringType, BlobType], NullType>;
+    /**
+     * Node.js implementation of file system platform functions.
+     *
+     * Pass this to {@link East.compile} to enable file system operations.
+     */
+    readonly Implementation: PlatformFunction[];
+};
+export { FileSystemImpl };
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAQ,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAapF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,YAAY,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,UAAU,CAA2D,CAAC;AAEjJ;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,EAAE,OAAO,UAAU,CAAC,EAAE,OAAO,QAAQ,CAAsE,CAAC;AAE9K;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,EAAE,OAAO,UAAU,CAAC,EAAE,OAAO,QAAQ,CAAuE,CAAC;AAEhL;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,QAAQ,CAA2D,CAAC;AAEjJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,WAAW,CAAyD,CAAC;AAE7I;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,UAAU,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,WAAW,CAA0D,CAAC;AAE/I;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,WAAW,CAA+D,CAAC;AAEzJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,QAAQ,CAAgE,CAAC;AAE3J;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,OAAO,UAAU,CAAC,CAAC,CAA2E,CAAC;AAEpM;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,kBAAkB,EAAE,mBAAmB,CAAC,CAAC,UAAU,CAAC,EAAE,QAAQ,CAA+D,CAAC;AAE3I;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,EAAE,OAAO,QAAQ,CAAC,EAAE,OAAO,QAAQ,CAA0E,CAAC;AAEtL;;;;GAIG;AACH,QAAA,MAAM,cAAc,EAAE,gBAAgB,EAkGrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU;IACnB;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;;;;;;;;;;;OAqBG;;IAGH;;;;OAIG;;CAEG,CAAC;AAGX,OAAO,EAAE,cAAc,EAAE,CAAC"}