posipaki 0.49.0 → 0.49.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posipaki",
-  "version": "0.49.0",
+  "version": "0.49.2",
   "homepage": "https://posipaki-docs.muromec.nl/",
   "repository": {
     "type": "git",

package/dist/actor-Df5v2zuv.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"actor-Df5v2zuv.js","names":[],"sources":["../src/port/split.ts","../src/port/held.ts","../src/port/actor.ts"],"sourcesContent":["// ── bytes into parts: the splitter ──────────────────────────────────────────\n//\n// Cuts a stream of bytes on 0x0a; what lies between two cuts is a line.  Every byte medium does this: a stdio pair,\n// a socket, an HTTP body.\n\n// Splitting on the byte is safe for UTF-8: a continuation byte is never 0x0a, so a character cannot be cut in\n// half.  A character that straddles two chunks waits in the buffer until the rest arrives.\n//\n// Text is decoded by a StringDecoder for the same reason: half a character waits rather than becoming two\n// replacement marks.\n//\n// A line may announce octets after it.  The splitter does not know that rule, so it is passed in: given a line,\n// how many raw octets follow it?  The seam answers with `$chunk`; a medium with no such thing answers none.\n\nimport { StringDecoder } from \"node:string_decoder\";\n\nimport type { Channel, Part } from \"./channel.js\";\n\nconst NL = 0x0a;\nconst CR = 0x0d;\n\n/** Given a line, how many raw octets follow it.  Default: none, this is a plain line. */\nexport type Announcement = (line: string) => number | null;\n\nconst NOTHING: Announcement = () => null;\n\n/**\n * One byte channel in, one channel of parts out.\n *\n * The returned channel's `send` is the same rule backwards: a part becomes its line, a terminator, and the\n * octets it carried.\n */\nexport function splitChannel<C = string>(\n  inner: Channel<Uint8Array, C>,\n  announced: Announcement = NOTHING,\n): Channel<Part, C> {\n  const readers = new Set<(part: Part) => void>();\n  const closers = new Set<(reason: C) => void>();\n  const failers = new Set<(error: unknown) => void>();\n  const decoder = new StringDecoder(\"utf8\");\n  /** Bytes that are not yet a frame: a line, or the octets a line announced. */\n  let buffered = Buffer.alloc(0);\n  /** The line whose announced octets are still arriving. */\n  let pending: { line: string; bytes: number } | null = null;\n  let ended = false;\n  let reason: C | null = null;\n\n  const emit = (part: Part): void => {\n    for (const reader of [...readers]) reader(part);\n  };\n\n  /** The far end is gone: our own readers hear it. */\n  const close = (why: C): void => {\n    if (ended) return;\n    ended = true;\n    reason = why;\n    for (const closer of [...closers]) closer(why);\n  };\n\n  /**\n   * End it here: the far end hears a close, our own readers do not, because we are the one who asked.  The\n   * reason stays null: a sentence from this side is not `C`, which is what the other end had to say.\n   */\n  const shut = (): void => {\n    if (ended) return;\n    ended = true;\n  };\n\n  /** Hand over what the buffer holds, as far as the framing allows. */\n  const drain = (): void => {\n    while (!ended) {\n      if (pending !== null) {\n        if (buffered.length < pending.bytes) return;\n        const bytes = buffered.subarray(0, pending.bytes);\n        buffered = buffered.subarray(pending.bytes);\n        const line = pending.line;\n        pending = null;\n        emit({ line, bytes: new Uint8Array(bytes) });\n        continue;\n      }\n      const cut = buffered.indexOf(NL);\n      if (cut === -1) return;\n      const raw = buffered.subarray(0, cut);\n      buffered = buffered.subarray(cut + 1);\n      const line = raw.length > 0 && raw[raw.length - 1] === CR ? raw.subarray(0, raw.length - 1) : raw;\n      const text = decoder.write(line);\n      const count = announced(text);\n      if (count === null) {\n        emit({ line: text, bytes: null });\n        continue;\n      }\n      pending = { line: text, bytes: count };\n      if (count === 0) {\n        pending = null;\n        emit({ line: text, bytes: new Uint8Array(0) });\n      }\n    }\n  };\n\n  inner.onFrame((chunk) => {\n    if (ended) return;\n    buffered = buffered.length === 0 ? Buffer.from(chunk) : Buffer.concat([buffered, Buffer.from(chunk)]);\n    drain();\n  });\n  inner.onError((error) => {\n    for (const failer of [...failers]) failer(error);\n  });\n  inner.onClose((why) => {\n    if (ended) return;\n    // Whatever is left without a terminator is still a line: a peer that hangs up after writing has said\n    // something, and dropping it would be the framing deciding to lose the last word.\n    if (pending === null && buffered.length > 0) {\n      const rest = buffered;\n      buffered = Buffer.alloc(0);\n      emit({ line: decoder.write(rest) + decoder.end(), bytes: null });\n    } else {\n      decoder.end();\n    }\n    close(why);\n  });\n\n  return {\n    send: async (part: Part) => {\n      const head = Buffer.from(`${part.line}\\n`, \"utf8\");\n      const body = part.bytes === null ? head : Buffer.concat([head, Buffer.from(part.bytes)]);\n      await inner.send(new Uint8Array(body));\n    },\n    onFrame: (handler) => {\n      readers.add(handler);\n      return () => {\n        readers.delete(handler);\n      };\n    },\n    onClose: (handler) => {\n      if (ended && reason !== null) {\n        handler(reason);\n        return () => {};\n      }\n      closers.add(handler);\n      return () => {\n        closers.delete(handler);\n      };\n    },\n    onError: (handler) => {\n      failers.add(handler);\n      return () => {\n        failers.delete(handler);\n      };\n    },\n    close: async (why = \"closed here\") => {\n      shut();\n      await inner.close(why);\n    },\n    info: inner.info,\n    control: (command) => inner.control(command),\n  };\n}\n","// ── a channel that keeps what nobody was reading yet ────────────────────────\n//\n// A medium can deliver a frame in the same turn a reader is being installed, and a channel with no subscriber\n// drops it.  This wraps a channel so nothing is dropped for want of a listener: what arrives while nobody is\n// subscribed is kept, and every subscriber that arrives before the first frame is delivered is given it.\n//\n// The window ends at the first delivery.  After that the channel is live, and a subscriber that comes later has\n// missed what went before it — which is what any live channel means, and the alternative would be an unbounded\n// copy of everything ever said.\n\nimport type { Channel } from \"./channel.js\";\n\n/**\n * `inner`, with the frames that arrive before anyone is subscribed kept for the readers that follow.\n *\n * The kept frames are not bounded, because a bound depends on what the far end may say before anyone listens,\n * and that is not something this adapter can know.\n */\nexport function held<F, C>(inner: Channel<F, C>): Channel<F, C> {\n  const readers = new Set<(frame: F) => void>();\n  const closers = new Set<(reason: C) => void>();\n  const failers = new Set<(error: unknown) => void>();\n  const kept: F[] = [];\n  let live = false;\n\n  const emit = (frame: F): void => {\n    for (const reader of [...readers]) reader(frame);\n  };\n\n  inner.onFrame((frame) => {\n    if (live) {\n      emit(frame);\n      return;\n    }\n    if (readers.size === 0) {\n      kept.push(frame);\n      return;\n    }\n    // Somebody is reading: from here the channel is live, and what was kept has been taken.\n    live = true;\n    kept.length = 0;\n    emit(frame);\n  });\n  inner.onClose((reason) => {\n    for (const closer of [...closers]) closer(reason);\n  });\n  inner.onError((error) => {\n    for (const failer of [...failers]) failer(error);\n  });\n\n  return {\n    send: (frame) => inner.send(frame),\n    onFrame(handler) {\n      readers.add(handler);\n      // Handed to every subscriber that arrives before the first delivery, not only to the first.\n      for (const frame of kept) handler(frame);\n      return () => {\n        readers.delete(handler);\n      };\n    },\n    onClose(handler) {\n      closers.add(handler);\n      return () => {\n        closers.delete(handler);\n      };\n    },\n    onError(handler) {\n      failers.add(handler);\n      return () => {\n        failers.delete(handler);\n      };\n    },\n    close: (reason) => inner.close(reason),\n    info: inner.info,\n    control: (command) => inner.control(command),\n  };\n}\n","// ── a port as an actor ──────────────────────────────────────────────────────\n//\n// One actor that owns one channel and speaks for it: what it is told to send goes in, what the channel delivers\n// comes out as DATA, and the way the channel ended is left in the actor's state, where a parent reads anyway.\n//\n// The channel is opened in `setup`, which the runtime awaits, so an actor that is ready has a channel: a send is\n// never asked to wait for one, and a port that cannot open fails its start rather than looking alive.  What a\n// channel is — a process, a socket, a pair in memory — is `open`'s business; the actor knows only that it has one.\n\nimport type { ActorDefinition } from \"../actor-types.js\";\nimport { defineActor, defineMessages } from \"../define-actor.js\";\nimport type { Message } from \"../types.js\";\nimport type { Channel } from \"./channel.js\";\n\n/** Write this to the channel. */\nexport interface SendMessage<F> extends Message {\n  type: \"SEND\";\n  data: F;\n}\n\n/** Ask the channel's own world to act on what is behind it; a medium without one ignores it. */\nexport interface SignalMessage extends Message {\n  type: \"SIGNAL\";\n  signal: string;\n}\n\n/** A frame the channel delivered. */\nexport interface DataMessage<F> extends Message {\n  type: \"DATA\";\n  data: F;\n}\n\nexport type PortIn<F> = SendMessage<F> | SignalMessage;\nexport type PortOut<F> = DataMessage<F>;\n\n/** What a parent may read of a port.  The ending is here because it is state, not news. */\nexport interface PortPublic<C> {\n  /** The channel is open.  False before it opens and after it has ended. */\n  alive: boolean;\n  /** How it ended, or null while it has not. */\n  end: C | null;\n  /** What the medium knows about itself — a process its pid — as the channel reported it. */\n  info: Record<string, unknown>;\n}\n\n/** What a medium's actor is handed: a name, and a way to open the channel it will own. */\nexport interface PortActorSpec<Args, F, C = string> {\n  name: string;\n  /** Opens the channel this actor owns.  Called once, when the actor starts. */\n  open(args: Args): Promise<Channel<F, C>>;\n}\n\ntype PortState<F, C> = {\n  public: PortPublic<C>;\n  private: { channel: Channel<F, C>; args: unknown };\n};\n\n/**\n * An actor over one channel.\n *\n * In `SEND {data}` writes to it and `SIGNAL {signal}` asks the medium to act on what is behind it, through\n * the channel's own `control`; posipaki's `STOP` ends the actor, which closes the channel.  Out `DATA {data}`\n * for every frame.  The channel's ending is left in `state.end`, what the medium knows about itself in\n * `state.info`, and then the actor stops.\n */\nexport function portActor<Args, F, C = string>(\n  spec: PortActorSpec<Args, F, C>,\n): ActorDefinition<Args, PortState<F, C>, PortIn<F>, PortOut<F>, {}> {\n  return defineActor({\n    name: spec.name,\n    inMessages: defineMessages<PortIn<F>>(),\n    outMessages: defineMessages<PortOut<F>>(),\n    setup: async (args: Args): Promise<PortState<F, C>> => {\n      const channel = await spec.open(args);\n      return {\n        public: { alive: true, end: null, info: channel.info },\n        private: { channel, args },\n      };\n    },\n    afterStart() {\n      const { channel } = this.state.private;\n      channel.onFrame((data) => {\n        this.emit({ type: \"DATA\", data });\n      });\n      channel.onClose((reason) => {\n        this.state.public.alive = false;\n        this.state.public.end = reason;\n        this.exit();\n      });\n    },\n    async beforeEnd() {\n      this.state.public.alive = false;\n      await this.state.private.channel.close();\n    },\n    handlers: {\n      async SEND(msg: SendMessage<F>) {\n        await this.state.private.channel.send(msg.data);\n      },\n      SIGNAL(msg: SignalMessage) {\n        this.state.private.channel.control({ signal: msg.signal });\n      },\n    },\n  });\n}\n"],"mappings":"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"}