@phreshos/node 0.1.12 → 0.1.14

package/dist/shell.js

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import ProcessTree from "./process-tree.js";
+/** Execute one command locally while its iterator owns the complete process tree. */
+export default function shell(command, options = {}) {
+    return (async function* () {
+        const input = validate(command, options);
+        const queue = [];
+        let wake = null;
+        let failure = null;
+        let closed = false;
+        let treeEnded = false;
+        let ending = null;
+        let settle;
+        const stopped = new Promise(resolve => { settle = resolve; });
+        const notify = () => {
+            wake?.();
+            wake = null;
+        };
+        const finish = () => {
+            if (!closed || !treeEnded || !ending)
+                return;
+            queue.push({
+                event: {
+                    event: "exited",
+                    exit: {
+                        status: ending.signal ? "signaled" : "exited",
+                        code: ending.code,
+                        signal: ending.signal
+                    }
+                }
+            });
+            settle();
+            notify();
+        };
+        const child = spawn(input.command, {
+            shell: true,
+            detached: true,
+            cwd: input.cwd,
+            env: { ...process.env, ...input.env },
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        const tree = new ProcessTree(child, (code, signal) => {
+            ending = { code, signal };
+            treeEnded = true;
+            finish();
+        });
+        const output = (stream, name) => {
+            stream.on("data", chunk => {
+                stream.pause();
+                queue.push({ event: { event: "output", stream: name, text: String(chunk) }, resume: () => stream.resume() });
+                notify();
+            });
+        };
+        const abort = () => {
+            failure = options.signal?.reason instanceof Error ? options.signal.reason : new Error("The shell command was cancelled");
+            tree.stop();
+            notify();
+        };
+        child.once("spawn", () => {
+            if (typeof child.pid !== "number") {
+                failure = new Error("The shell command started without a process identity");
+                tree.stop();
+            }
+            else {
+                queue.push({ event: { event: "started", pid: child.pid } });
+            }
+            notify();
+        });
+        child.once("error", error => {
+            failure = error;
+            settle();
+            notify();
+        });
+        child.once("close", () => {
+            closed = true;
+            finish();
+        });
+        output(child.stdout, "stdout");
+        output(child.stderr, "stderr");
+        if (options.signal?.aborted)
+            abort();
+        else
+            options.signal?.addEventListener("abort", abort, { once: true });
+        try {
+            while (true) {
+                if (failure)
+                    throw failure;
+                const next = queue.shift();
+                if (next) {
+                    yield next.event;
+                    next.resume?.();
+                    if (next.event.event === "exited")
+                        return;
+                    continue;
+                }
+                await new Promise(resolve => { wake = resolve; });
+            }
+        }
+        finally {
+            options.signal?.removeEventListener("abort", abort);
+            if (!closed || !treeEnded)
+                tree.stop();
+            await stopped;
+        }
+    })();
+}
+function validate(command, options) {
+    if (typeof command !== "string" || !command.trim())
+        throw new Error("A shell command must be non-empty text");
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new Error("Shell options must be an object");
+    if (Object.keys(options).some(key => key !== "cwd" && key !== "env" && key !== "signal"))
+        throw new Error("Shell options contain an unknown field");
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal))
+        throw new Error("A shell signal must be an AbortSignal");
+    const cwd = options.cwd ?? homedir();
+    const env = options.env ?? {};
+    if (typeof cwd !== "string" || !cwd)
+        throw new Error("A shell working directory must be non-empty text");
+    if (!env || typeof env !== "object" || Array.isArray(env) || Object.values(env).some(value => typeof value !== "string")) {
+        throw new Error("Shell environment values must be text");
+    }
+    return { command, cwd, env };
+}

package/dist/storage.d.ts

@@ -1,3 +1,7 @@
-import type { SystemStorage } from "@phreshos/core";
+import type { Storage } from "@phreshos/core";
 /** Create one filesystem implementation bounded beneath a resolved absolute root. */
-export declare function filesystemStorage(source: string | (() => Promise<string>), label: string): SystemStorage;
+export declare function filesystemStorage(source: string | (() => Promise<string>), label: string, lifetime?: Lifetime): Storage;
+/** Create native filesystem access entered from one resolved absolute path. */
+export declare function nativeStorage(source: string | (() => Promise<string>), label: string, lifetime?: Lifetime): Storage;
+type Lifetime = () => AbortSignal;
+export {};

package/dist/storage.js

@@ -1,39 +1,51 @@
 import { randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 /** Create one filesystem implementation bounded beneath a resolved absolute root. */
-export function filesystemStorage(source, label) {
+export function filesystemStorage(source, label, lifetime) {
+    return createStorage(source, label, contained, lifetime);
+}
+/** Create native filesystem access entered from one resolved absolute path. */
+export function nativeStorage(source, label, lifetime) {
+    return createStorage(source, label, (root, parts) => resolvePath(root, ...parts), lifetime);
+}
+function createStorage(source, label, locate, lifetime) {
     let root = null;
     const resolveRoot = () => {
+        active(lifetime);
         if (!root)
             root = Promise.resolve(typeof source === "string" ? source : source()).then(value => {
+                active(lifetime);
                 if (!isAbsolute(value))
                     throw new Error("A Storage root must be absolute");
                 return value;
             });
         return root;
     };
-    const path = () => resolveRoot();
-    const resolve = async (...parts) => contained(await path(), parts);
+    const path = async () => await resolveRoot();
+    const resolve = async (...parts) => locate(await path(), parts);
     async function stream(...parts) {
+        const signal = active(lifetime);
         const destination = await resolve(...parts);
         const found = describe(destination);
         if (!found)
             throw new Error(`There is no ${parts.join("/")} in ${label}`);
         if (found.kind !== "file")
             throw new Error(`${parts.join("/")} is not a file`);
-        return Readable.toWeb(createReadStream(destination));
+        return Readable.toWeb(createReadStream(destination, { signal }));
     }
     async function write(...args) {
+        const signal = active(lifetime);
         const parts = args.slice(0, -1);
         const destination = await resolve(...parts);
         const temporary = join(dirname(destination), `.${randomUUID()}.writing`);
         mkdirSync(dirname(destination), { recursive: true });
         try {
-            await pipeline(Readable.fromWeb(content(args.at(-1))), createWriteStream(temporary, { flags: "wx" }));
+            await pipeline(Readable.fromWeb(content(args.at(-1))), createWriteStream(temporary, { flags: "wx" }), { signal });
+            signal?.throwIfAborted();
             renameSync(temporary, destination);
         }
         catch (error) {
@@ -49,14 +61,16 @@ export function filesystemStorage(source, label) {
         async text(...parts) { return new Response(await stream(...parts)).text(); },
         async json(...parts) { return JSON.parse(await new Response(await stream(...parts)).text()); },
         write,
-        async stat(...parts) { return describe(await resolve(...parts)); },
-        async list(...parts) { return readdirSync(await resolve(...parts)).sort(); },
+        async stat(...parts) { active(lifetime); return describe(await resolve(...parts)); },
+        async list(...parts) { active(lifetime); return readdirSync(await resolve(...parts)).sort(); },
         async delete(...parts) {
+            active(lifetime);
             if (!parts.length)
                 throw new Error("Emptying a place is clear, not delete");
             rmSync(await resolve(...parts), { recursive: true, force: true });
         },
         async clear(...parts) {
+            active(lifetime);
             const destination = await resolve(...parts);
             const found = describe(destination);
             if (found && found.kind !== "directory")
@@ -66,6 +80,11 @@ export function filesystemStorage(source, label) {
         }
     };
 }
+function active(lifetime) {
+    const signal = lifetime?.();
+    signal?.throwIfAborted();
+    return signal;
+}
 function content(value) {
     if (value instanceof ReadableStream)
         return value;

package/dist/system.d.ts

@@ -1,42 +1,48 @@
-import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, type ProgramDefinition, type ServiceKey, type System as CoreSystem, type SystemClientEntity, type SystemEndpointEntity, type SystemProcessEntity, type SystemProcess, type SystemProcessRunEvent, type SystemProcessRunOptions, type SystemProgram, type SystemProgramEntity, type SystemServerEntity, type SystemUploads, type SystemStorage, type WritableAppearance } from "@phreshos/core";
-export type ProgramProcessRunOptions = SystemProcessRunOptions;
-export type ProgramProcessRunEvent = SystemProcessRunEvent;
+import { ClientEndpoint as CoreClientEndpoint, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, ServerService as CoreServerService, type ProgramDefinition, type ProgramProcessRunEvent as CoreProgramProcessRunEvent, type ProgramProcessRunOptions as CoreProgramProcessRunOptions, type ServiceKey, type ShellOptions, type System as CoreSystem, type SystemProcess, type SystemProgram, type SystemUploads, type Storage, type WritableAppearance } from "@phreshos/core";
+export type ProgramProcessRunOptions = CoreProgramProcessRunOptions;
+export type ProgramProcessRunEvent = CoreProgramProcessRunEvent;
+type ServiceEndpoint = ServiceKey["endpoint"];
+type ServiceAddress<Endpoint extends ServiceEndpoint> = Omit<ServiceKey, "endpoint"> & Readonly<{
+    endpoint: Endpoint;
+}>;
+type ServiceHandle<Endpoint extends ServiceEndpoint, EventsMap extends object, Fallback = unknown> = Endpoint extends "server" ? ServerService<EventsMap, Fallback> : ClientService<EventsMap, Fallback>;
 /** One connected owner-local implementation of the shared System contract. */
 export declare class System implements CoreSystem {
-    readonly storage: SystemStorage;
+    readonly storage: Storage;
     readonly appearance: WritableAppearance;
     readonly program: SystemProgram;
     readonly process: SystemProcess;
     readonly uploads: SystemUploads;
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    websocket(url: string | URL, protocols?: string | string[]): Promise<WebSocket>;
+    shell(command: string, options?: ShellOptions): AsyncGenerator<import("@phreshos/core").ShellEvent, void, void>;
     private constructor();
     /** Connect to the System selected by argument, environment, or owner default. */
     static connect(home?: string): Promise<System>;
     /** Atomically replace one runtime Program without touching its installed form. */
-    forceCreateProgram(source: ProgramDefinition | string): Promise<SystemProgramEntity>;
+    forceCreateProgram(source: ProgramDefinition | string): Promise<Program>;
     /** Close this owner connection and abort every attached operation it owns. */
     disconnect(): Promise<void>;
-    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceKey & {
-        endpoint: "server";
-    }): ServerService<EventsMap, Fallback>;
-    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceKey & {
-        endpoint: "client";
-    }): ClientService<EventsMap, Fallback>;
+    service<Endpoint extends ServiceEndpoint>(key: ServiceAddress<Endpoint>): ServiceHandle<Endpoint, {}>;
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceAddress<"server">): ServerService<EventsMap, Fallback>;
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceAddress<"client">): ClientService<EventsMap, Fallback>;
 }
-/** Node-SDK handle for a Service provided by a Server Endpoint. */
+/** Node SDK handle for a Service provided by a Server Endpoint. */
 export declare class ServerService<EventsMap extends object = {}, Fallback = unknown> extends CoreServerService<EventsMap, Fallback> {
     protected constructor();
 }
-/** Node-SDK handle for a Service provided by a Client Endpoint. */
+/** Node SDK handle for a Service provided by a Client Endpoint. */
 export declare class ClientService<EventsMap extends object = {}, Fallback = unknown> extends CoreClientService<EventsMap, Fallback> {
     protected constructor();
 }
-export type Program = SystemProgramEntity;
+export type Program = CoreProgram;
 export declare const Program: typeof CoreProgram;
-export type Process = SystemProcessEntity;
+export type Process = CoreProcess;
 export declare const Process: typeof CoreProcess;
-export type Endpoint<EventsMap extends object = {}, Fallback = unknown> = SystemEndpointEntity<EventsMap, Fallback>;
+export type Endpoint<EventsMap extends object = {}, Fallback = unknown> = CoreEndpoint<EventsMap, Fallback>;
 export declare const Endpoint: typeof CoreEndpoint;
-export type Server<EventsMap extends object = {}, Fallback = unknown> = SystemServerEntity<EventsMap, Fallback>;
-export declare const Server: typeof CoreServer;
-export type Client<EventsMap extends object = {}, Fallback = unknown> = SystemClientEntity<EventsMap, Fallback>;
-export declare const Client: typeof CoreClient;
+export type ServerEndpoint<EventsMap extends object = {}, Fallback = unknown> = CoreServerEndpoint<EventsMap, Fallback>;
+export declare const ServerEndpoint: typeof CoreServerEndpoint;
+export type ClientEndpoint<EventsMap extends object = {}, Fallback = unknown> = CoreClientEndpoint<EventsMap, Fallback>;
+export declare const ClientEndpoint: typeof CoreClientEndpoint;
+export {};