@phreshos/core 0.1.0 → 0.1.2

package/source/main.ts

@@ -1,65 +0,0 @@
-export {
-  type Message,
-  type Cleanup,
-  type Capture,
-  type Captures,
-  type EventMessage,
-  type EventName,
-  type EventObserver,
-  type EventOptions,
-  type EventSubscriber,
-  type Subscribable
-} from "./subscribable.js"
-
-export { type Publishable } from "./publishable.js"
-export { type Askable, type TimedAskable } from "./askable.js"
-export { type Outcome } from "./outcome.js"
-export { type ServedFile } from "./served-file.js"
-export {
-  type DirectoryStat,
-  type EntryStat,
-  type FileStat,
-  type OtherStat,
-  type ProgramArea,
-  type ProgramStore
-} from "./storage.js"
-export { type LogKind, type LogRecord, type LogSource, type ProgramSql } from "./sql.js"
-
-export {
-  Endpoint,
-  type AskCapture,
-  type AskMessage,
-  type AskObserver,
-  type EndpointTraffic,
-  type TrafficCapture,
-  type TrafficEvents,
-  type TrafficMessage
-} from "./endpoint.js"
-export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js"
-export {
-  Server,
-  type AnswerCapture,
-  type AnswerMessage,
-  type AnswerObserver,
-  type ServerTraffic
-} from "./server.js"
-export { Client, type ClientTraffic } from "./client.js"
-export { Process, type Exit, type ProcessEvents } from "./process.js"
-export {
-  Program,
-  type ClientDeclaration,
-  type EndpointDeclaration,
-  type ProgramEvents,
-  type ProgramProcessExit,
-  type ProgramServerStop
-} from "./program.js"
-export { Window, type WindowEvents, type WindowState } from "./window.js"
-export { layers, type Launch, type LaunchClient, type Layer, type Position, type Size, type Value } from "./launch.js"
-export {
-  defineConfig,
-  type ClientConfig,
-  type ClientDevelopment,
-  type Config,
-  type ServerConfig,
-  type ServerDevelopment
-} from "./config.js"

package/source/outcome.ts

@@ -1,4 +0,0 @@
-/** The transport-neutral result of an operation that may fail. */
-export type Outcome<Result = unknown> =
-  | Readonly<{ success: true, result: Result }>
-  | Readonly<{ success: false, error: string }>

package/source/process.ts

@@ -1,77 +0,0 @@
-import type { Client } from "./client.js"
-import type { Program } from "./program.js"
-import type { Server } from "./server.js"
-import type { Subscribable } from "./subscribable.js"
-
-/** How an operating-system-backed endpoint or Process finished. */
-export type Exit = Readonly<{
-  /** Whether the endpoint exited normally or was terminated by a signal. */
-  status: "exited" | "signaled"
-
-  /** Numeric exit code, or `null` when no code was reported. */
-  code: number | null
-
-  /** Signal name, or `null` when no signal ended it. */
-  signal: string | null
-}>
-
-/** Lifecycle events emitted by one Process. */
-export type ProcessEvents = {
-  /** The Server entered a new live incarnation. */
-  serverStart: undefined
-
-  /** The Server incarnation ended. */
-  serverStop: Omit<Exit, "status">
-
-  /** The authoritative Client state was created. */
-  clientStart: undefined
-
-  /** The authoritative Client state ended. */
-  clientStop: undefined
-
-  /** The complete Process ended. */
-  exit: Exit
-}
-
-/** One live execution of a Program. */
-export class Process<Events extends object = {}> {
-  public constructor() {}
-}
-
-export interface Process<Events extends object = {}> extends Subscribable<ProcessEvents & Events, never> {
-  /** Immutable runtime identity. */
-  readonly identity: string
-
-  /** Optional meaningful name unique among this Program's live Processes. */
-  readonly name: string | null
-
-  /** Instant at which this Process was created. */
-  readonly startedAt: Date
-
-  /** Permanent handle to this Process's Server. */
-  readonly server: Server
-
-  /** Permanent handle to this Process's Client. */
-  readonly client: Client
-
-  /** Returns the Program that owns this Process. */
-  program(): Program
-
-  /**
-   * Returns the Process whose `createProcess()` call created this Process.
-   *
-   * Returns `null` when this Process has no accessible parent handle. Rejects
-   * when this Process or its retained parent no longer exists. Client
-   * environments never expose a parent belonging to another Program.
-   */
-  parent(): Promise<Process | null>
-
-  /** Returns one immutable launch option. */
-  option(name: string): Promise<string | undefined>
-
-  /** Ends the complete Process and all live Endpoints. */
-  exit(): Promise<void>
-
-  /** Returns whether this Process has ended. */
-  exited(): Promise<boolean>
-}

package/source/program.ts

@@ -1,130 +0,0 @@
-import type { Launch, Layer, Position, Size } from "./launch.js"
-import type { Exit, Process } from "./process.js"
-import type { ProgramSql } from "./sql.js"
-import type { ProgramArea, ProgramStore } from "./storage.js"
-import type { Subscribable } from "./subscribable.js"
-
-/** Resolved declaration shared by Server and Client endpoint kinds. */
-export type EndpointDeclaration = Readonly<{
-  /** Whether a default Process starts this declared Endpoint. */
-  start: boolean
-}>
-
-/** Resolved Client declaration and its default Window state. */
-export type ClientDeclaration = EndpointDeclaration & Readonly<{
-  /** Default Window title, or `null` when the system supplies it. */
-  title: string | null
-
-  /** Default Window size, or `null` when the system supplies it. */
-  size: Size | null
-
-  /** Default Window position, or `null` when the system supplies it. */
-  position: Position | null
-
-  /** Default Window layer, or `null` for the system default. */
-  layer: Layer | null
-
-  /** Default minimized state, or `null` for the system default. */
-  minimize: boolean | null
-}>
-
-export type ProgramProcessExit = Exit & Readonly<{
-  /** Process that ended. */
-  process: Process
-}>
-
-export type ProgramServerStop = Omit<Exit, "status"> & Readonly<{
-  /** Process whose Server incarnation ended. */
-  process: Process
-}>
-
-/** Lifecycle events scoped to one Program. */
-export type ProgramEvents = {
-  /** One Process's Server entered a new live incarnation. */
-  serverStart: Process
-
-  /** One Process's Server incarnation ended. */
-  serverStop: ProgramServerStop
-
-  /** One Process's Client state was created. */
-  clientStart: Process
-
-  /** One Process's Client state ended. */
-  clientStop: Process
-
-  /** A Process entered this Program's runtime set. */
-  processCreate: Process
-
-  /** A Process left this Program's runtime set. */
-  processExit: ProgramProcessExit
-
-  /** This Program left the runtime registry. */
-  forget: undefined
-
-  /** This Program left the installed state. */
-  uninstall: Readonly<{ everythingRemoved: boolean }>
-}
-
-/** The stable domain root from which Processes are created. */
-export class Program<Events extends object = {}> {
-  public constructor() {}
-}
-
-export interface Program<Events extends object = {}> extends Subscribable<ProgramEvents & Events, never> {
-  /** Stable public identity. */
-  readonly identity: string
-
-  /** Human-readable name. */
-  readonly name: string
-
-  /** Declared version, or `null`. */
-  readonly version: string | null
-
-  /** Declared description, or `null`. */
-  readonly description: string | null
-
-  /** Server declaration, or `null` when this Program cannot start one. */
-  readonly server: EndpointDeclaration | null
-
-  /** Client declaration, or `null` when this Program cannot start one. */
-  readonly client: ClientDeclaration | null
-
-  /** Persistent filesystem data shared by every Process of this Program. */
-  readonly data: ProgramArea
-
-  /** Disposable filesystem data shared by every Process of this Program. */
-  readonly cache: ProgramArea
-
-  /** Persistent key-value storage shared by every Process of this Program. */
-  readonly store: ProgramStore
-
-  /** Read-only SQL access to captured Client and Server output. */
-  readonly logs: ProgramSql
-
-  /** Writable SQLite database owned by this Program. */
-  readonly database: ProgramSql
-
-  /** Returns every live Process of this Program available to this SDK. */
-  processes(): Promise<Process[]>
-
-  /** Finds a live Process by identity or Program-local name. */
-  getProcess(identityOrName: string): Promise<Process | null>
-
-  /** Creates one Process of this Program. */
-  createProcess(launch?: Launch): Promise<Process>
-
-  /** Returns the official Markdown API entry point, or `null`. */
-  apiDocs(): Promise<string | null>
-
-  /** Returns whether this Program currently has an installed form. */
-  installed(): Promise<boolean>
-
-  /** Removes this Program's installed form. */
-  uninstall(everything?: boolean): Promise<void>
-
-  /** Ends all Processes and removes this Program from the runtime registry. */
-  forget(): Promise<void>
-
-  /** Ends every live Process and returns their identities. */
-  exitAll(): Promise<string[]>
-}

package/source/publishable.ts

@@ -1,33 +0,0 @@
-import type { EventMessage, EventName } from "./subscribable.js"
-
-// Preserves declared string literals in editor completion while still
-// accepting application-defined event names.
-type OpenEvent = string & {}
-
-type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent)
-
-type CompatibleEvent<Events extends object, Fallback, Payload> = {
-  [Event in EventName<Events>]: Payload extends Events[Event] ? Event : never
-}[EventName<Events>] | ([Fallback] extends [never] ? never : Payload extends Fallback ? OpenEvent : never)
-
-interface Publish<Events extends object, Fallback> {
-  <Payload, Event extends CompatibleEvent<Events, Fallback, Payload> = CompatibleEvent<Events, Fallback, Payload>>(
-    event: Event,
-    payload: Payload
-  ): void
-  <Event extends AvailableEvent<Events, Fallback>>(
-    event: Event,
-    payload: EventMessage<Events, Fallback, Event>
-  ): void
-}
-
-/**
- * The independent capability to publish one payload to a named event.
- *
- * Publishing is synchronous and fire-and-forget. An unavailable destination
- * silently drops the publication; no delivery result is produced.
- */
-export interface Publishable<Events extends object = {}, Fallback = unknown> {
-  /** Publishes one payload to one named event on this target. */
-  publish: Publish<Events, Fallback>
-}

package/source/served-file.ts

@@ -1,14 +0,0 @@
-/** Description of a value stored as a publicly reachable file. */
-export type ServedFile = Readonly<{
-  /** Generated filename beneath the public served-files route. */
-  file: string
-
-  /** Detected media type, or `null` when no type is known. */
-  type: string | null
-
-  /** Stored size in bytes. */
-  size: number
-
-  /** Storage time as Unix milliseconds. */
-  time: number
-}>

package/source/server.ts

@@ -1,58 +0,0 @@
-import type { Askable } from "./askable.js"
-import { Endpoint, type EndpointTraffic } from "./endpoint.js"
-import type { Outcome } from "./outcome.js"
-import type { Cleanup } from "./subscribable.js"
-
-/** One answer sent by this Server to the Endpoint that asked. */
-export type AnswerMessage<Result = unknown, To = Endpoint> = Readonly<{
-  /** Destination Endpoint, or `null` when its identity is outside this boundary. */
-  to: To
-
-  /** Transport-neutral success or failure returned by the answerer. */
-  outcome: Outcome<Result>
-}>
-
-/** One observed answer sent by this Server. */
-export type AnswerCapture<Result = unknown, To = Endpoint> = Readonly<{
-  /** Event originally addressed by the question. */
-  event: string
-
-  /** Correlation identity shared with the original question. */
-  questionId: string
-
-  /** Answer destination and outcome. */
-  message: AnswerMessage<Result, To>
-}>
-
-/** A callback that observes answers sent by this Server. */
-export type AnswerObserver<Result = unknown, To = Endpoint> = (capture: AnswerCapture<Result, To>) => unknown
-
-/** Broad communication originating from one Server, including its answers. */
-export interface ServerTraffic<
-  Events extends object = {},
-  To = Endpoint,
-  AskTo = Server
-> extends EndpointTraffic<Events, To, AskTo> {
-  /** Observes answers originating from this Server. */
-  observeAnswers<Result = unknown>(observer: AnswerObserver<Result, To>): Cleanup
-}
-
-/** The server Endpoint of a Process. */
-export class Server<Events extends object = {}> extends Endpoint<Events> {
-  public constructor() {
-    super()
-  }
-}
-
-export interface Server<Events extends object = {}> extends Askable {
-  /** Broad communication originating from this Server. */
-  readonly traffic: ServerTraffic<Events>
-
-  /**
-   * Waits until a Server incarnation is ready.
-   *
-   * Temporary absence remains waitable when the Program declares a Server.
-   * The SDK uses its ten-second deadline unless one is supplied.
-  */
-  waitReady(timeout?: number): Promise<void>
-}

package/source/sql.ts

@@ -1,36 +0,0 @@
-/** SQL access to a Program-owned database or its read-only logs. */
-export interface ProgramSql {
-  /** Executes one statement; template interpolations become bound values. */
-  query<Row = Record<string, unknown>>(
-    statement: TemplateStringsArray,
-    ...values: unknown[]
-  ): Promise<Row[]>
-
-  /** Executes one statement with optional bound values. */
-  query<Row = Record<string, unknown>>(
-    statement: string,
-    values?: unknown[]
-  ): Promise<Row[]>
-}
-
-/** One captured line from a Program endpoint. */
-export type LogRecord = Readonly<{
-  createdAt: number
-  process: string
-  source: LogSource
-  kind: LogKind
-  content: string
-}>
-
-export type LogSource = "client" | "server"
-
-export type LogKind =
-  | "debug"
-  | "log"
-  | "info"
-  | "warn"
-  | "error"
-  | "stdout"
-  | "stderr"
-  | "exit"
-  | (string & {})

package/source/storage.ts

@@ -1,66 +0,0 @@
-/** Metadata returned for an entry in Program-owned filesystem storage. */
-export type EntryStat = FileStat | DirectoryStat | OtherStat
-
-export type FileStat = Readonly<{
-  kind: "file"
-  size: number
-  modifiedAt: number
-}>
-
-export type DirectoryStat = Readonly<{
-  kind: "directory"
-  modifiedAt: number
-}>
-
-export type OtherStat = Readonly<{
-  kind: "other"
-  modifiedAt: number
-}>
-
-/** Filesystem-like storage owned by one Program. */
-export interface ProgramArea {
-  /** Reads one file as bytes. */
-  bytes(...path: string[]): Promise<Uint8Array>
-
-  /** Reads one UTF-8 text file. */
-  text(...path: string[]): Promise<string>
-
-  /** Reads and parses one JSON file. */
-  json<Value = unknown>(...path: string[]): Promise<Value>
-
-  /** Opens one file as a byte stream. */
-  stream(...path: string[]): Promise<ReadableStream<Uint8Array>>
-
-  /** Atomically writes one supported value, including a byte stream. */
-  write(...arguments_: [...path: string[], value: unknown]): Promise<void>
-
-  /** Returns entry metadata, or `null` when the entry does not exist. */
-  stat(...path: string[]): Promise<EntryStat | null>
-
-  /** Lists the sorted names immediately inside one directory. */
-  list(...path: string[]): Promise<string[]>
-
-  /** Recursively removes an entry. A missing entry is accepted. */
-  delete(...path: string[]): Promise<void>
-
-  /** Removes every entry while preserving the area itself. */
-  clear(): Promise<void>
-}
-
-/** Persistent key-value storage owned by one Program. */
-export interface ProgramStore {
-  /** Returns a value, or `undefined` when its key is absent or expired. */
-  get<Value = unknown>(key: string): Promise<Value | undefined>
-
-  /** Stores a value and optionally expires it after `ttl` milliseconds. */
-  set<Value>(key: string, value: Value, ttl?: number): Promise<boolean>
-
-  /** Deletes one key or several keys and reports whether anything changed. */
-  delete(key: string | string[]): Promise<boolean>
-
-  /** Returns whether a non-expired value exists for one key. */
-  has(key: string): Promise<boolean>
-
-  /** Deletes every value in this Program's store. */
-  clear(): Promise<void>
-}

package/source/subscribable.ts

@@ -1,94 +0,0 @@
-/** The unconstrained message received by a general Subscribable. */
-export type Message = unknown
-
-/** The message observed for one event on a Subscribable. */
-export type Capture<Event extends string = string, Received = Message> = Readonly<{
-  /** Name under which the message was published. */
-  event: Event
-
-  /** Message delivered by the observed target. */
-  message: Received
-}>
-
-/** The string event names declared by an event map. */
-export type EventName<Events extends object> = Extract<keyof Events, string>
-
-/** The message declared for one event name. */
-export type EventMessage<Events extends object, Fallback, Event extends string> = Event extends EventName<Events> ? Events[Event] : Fallback
-
-/** The correlated union observed across every event declared by a target. */
-export type Captures<Events extends object, Fallback = never> = {
-  [Event in EventName<Events>]: Capture<Event, Events[Event]>
-}[EventName<Events>] | ([Fallback] extends [never] ? never : Capture<string, Fallback>)
-
-/** A callback for one subscribed message. Its return value is not communication. */
-export type EventSubscriber<Message> = (message: Message) => unknown
-
-/** A callback for an observed event and its message. */
-export type EventObserver<Events extends object, Fallback = never> = (capture: Captures<Events, Fallback>) => unknown
-
-/** Removes exactly one persistent registration. Safe to call more than once. */
-export type Cleanup = () => void
-
-/** Options controlling one asynchronous event iterator. */
-export type EventOptions = Readonly<{
-  /** Maximum queued messages. Defaults to `64`; `Infinity` removes the bound. */
-  capacity?: number
-
-  /** Aborts iteration and removes its temporary boundary registration. */
-  signal?: AbortSignal
-}>
-
-// Preserves declared string literals in editor completion while still
-// accepting application-defined event names.
-type OpenEvent = string & {}
-
-type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent)
-
-type CompatibleEvent<Events extends object, Fallback, Narrowed> = {
-  [Event in EventName<Events>]: Narrowed extends Events[Event] ? Event : never
-}[EventName<Events>] | ([Fallback] extends [never] ? never : Narrowed extends Fallback ? OpenEvent : never)
-
-interface Subscribe<Events extends object, Fallback> {
-  <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, subscriber: EventSubscriber<Narrowed>): Cleanup
-  <Event extends AvailableEvent<Events, Fallback>>(event: Event, subscriber: EventSubscriber<EventMessage<Events, Fallback, Event>>): Cleanup
-}
-
-interface WaitFor<Events extends object, Fallback> {
-  <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, timeout?: number): Promise<Narrowed>
-  <Event extends AvailableEvent<Events, Fallback>>(event: Event, timeout?: number): Promise<EventMessage<Events, Fallback, Event>>
-}
-
-interface EventStream<Events extends object, Fallback> {
-  <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, options?: EventOptions): AsyncIterableIterator<Narrowed>
-  <Event extends AvailableEvent<Events, Fallback>>(event: Event, options?: EventOptions): AsyncIterableIterator<EventMessage<Events, Fallback, Event>>
-}
-
-interface Observe<Events extends object, Fallback> {
-  (observer: EventObserver<Events, Fallback>): Cleanup
-}
-
-/**
- * The common receiving capability supplied by environment SDKs.
- *
- * Persistent registrations return their sole cleanup function. A registration
- * may remain active across temporary endpoint absence and is removed only by
- * that cleanup or by destruction of its owning boundary.
- *
- * `waitFor()` uses the SDK's ten-second deadline unless one is supplied.
- * `events()` is long-lived instead: it ends when iteration is closed, its
- * signal aborts, or the boundary proves that future delivery is impossible.
- */
-export interface Subscribable<Events extends object = {}, Fallback = unknown> {
-  /** Registers one persistent named-event subscription. */
-  subscribe: Subscribe<Events, Fallback>
-
-  /** Waits for the next matching message. */
-  waitFor: WaitFor<Events, Fallback>
-
-  /** Iterates matching messages until closed, aborted, or impossible. */
-  events: EventStream<Events, Fallback>
-
-  /** Registers one persistent observer across every event on this target. */
-  observe: Observe<Events, Fallback>
-}

package/source/window.ts

@@ -1,82 +0,0 @@
-import type { Client } from "./client.js"
-import type { Layer, Position, Size } from "./launch.js"
-import type { Subscribable } from "./subscribable.js"
-
-/** Events emitted when authoritative Window state changes. */
-export type WindowEvents = {
-  move: Position
-  resize: Size
-  minimize: boolean
-  changeTitle: string
-  front: boolean
-}
-
-/** Current authoritative Window state. */
-export type WindowState = Readonly<{
-  /** Current title. */
-  title: string
-
-  /** Current top-left position. */
-  position: Position
-
-  /** Current width and height. */
-  size: Size
-
-  /** Whether the Window is minimized. */
-  minimized: boolean
-
-  /** Whether the Window is frontmost in its layer. */
-  front: boolean
-
-  /** Structurally isolated desktop layer containing the Window. */
-  layer: Layer
-
-  /** Current page beneath the declared Client location. */
-  location: string
-}>
-
-/** The Window owned by one live Client. */
-export class Window<Events extends object = {}> {
-  public constructor() {}
-}
-
-export interface Window<Events extends object = {}> extends Subscribable<WindowEvents & Events, never> {
-  /** Returns the Client that owns this Window. */
-  client(): Client
-
-  /** Returns the current title. */
-  title(): Promise<string>
-
-  /** Returns the current top-left position. */
-  position(): Promise<Position>
-
-  /** Returns the current width and height. */
-  size(): Promise<Size>
-
-  /** Returns whether the Window is minimized. */
-  minimized(): Promise<boolean>
-
-  /** Returns whether the Window is frontmost in its layer. */
-  front(): Promise<boolean>
-
-  /** Returns the structurally isolated desktop layer containing the Window. */
-  layer(): Promise<Layer>
-
-  /** Returns the current page rooted beneath the declared Client location. */
-  location(): Promise<string>
-
-  /** Moves the authoritative Window. */
-  move(position: Position): Promise<void>
-
-  /** Resizes the authoritative Window. */
-  resize(size: Size): Promise<void>
-
-  /** Changes whether the Window is minimized. */
-  minimize(minimized?: boolean): Promise<void>
-
-  /** Changes the Window title. */
-  changeTitle(title: string): Promise<void>
-
-  /** Brings the Window to the front of its own layer. */
-  raise(): Promise<void>
-}