@pipedog/core 0.0.0 → 0.1.0

package/dist/utils/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Types shared across Pipecat, independent of any provider SDK.
+ *
+ * The `NOT_GIVEN` sentinel lives here so that settings, contexts and anything
+ * else needing "this value was not provided" share one meaning. Provider SDKs
+ * ship their own equivalents; those belong to the SDK and are translated at the
+ * adapter boundary rather than used inside Pipecat.
+ */
+/**
+ * Sentinel type meaning "this value was not provided".
+ *
+ * Distinct from `null`, which is a meaningful value in most of the places
+ * this is used (typically "this service doesn't support this field").
+ * `NOT_GIVEN` is the singleton instance; test for it with `isGiven()`
+ * rather than comparing directly.
+ *
+ * DIVERGENCE: upstream makes the sentinel falsy (`__bool__` returns False) so
+ * `value or default` treats a missing value as absent. JavaScript objects are
+ * always truthy, so use `isGiven(value) ? value : fallback` instead.
+ */
+export declare class NotGiven {
+    #private;
+    /** Return the singleton instance, creating it on first use. */
+    constructor();
+    /** Return the sentinel's name. */
+    toString(): string;
+    toJSON(): string;
+}
+/** Singleton sentinel meaning "this value was not provided". */
+export declare const NOT_GIVEN: NotGiven;
+/**
+ * Check whether a value was explicitly provided.
+ *
+ * Also acts as a type guard: inside a true branch, the value is narrowed to
+ * exclude `NotGiven` (e.g. `string | null | NotGiven` becomes `string | null`).
+ *
+ * @example
+ * if (isGiven(delta.voice)) {
+ *   // caller wants to change the voice
+ * }
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is anything other than `NOT_GIVEN`.
+ */
+export declare function isGiven<T>(value: T | NotGiven): value is T;
+/**
+ * Extract a value that must have been provided.
+ *
+ * Intended for reads where `NOT_GIVEN` should never appear, such as a
+ * store-mode settings object (see `services/settings`). Narrows away
+ * `NotGiven` at the type level and throws at runtime if that invariant is
+ * violated.
+ *
+ * @example
+ * const resolvedModel = assertGiven(this._settings.model); // narrowed string | null
+ *
+ * @param value The value to extract.
+ * @returns The value, narrowed to exclude `NotGiven`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ */
+export declare function assertGiven<T>(value: T | NotGiven): T;
+/**
+ * Extract a value that must have been provided and must not be empty.
+ *
+ * Like `assertGiven()`, but also rejects `null` (and `undefined`) and the
+ * empty string, which is what an unset or blank environment variable
+ * produces. Use it for settings a service cannot work without, such as a
+ * local model or voice that no provider will validate on its behalf.
+ *
+ * @example
+ * const voice = requireGiven(this._settings.voice, "Piper TTS voice"); // narrowed string
+ *
+ * @param value The value to extract.
+ * @param what How to name the value in the error, e.g. `"Piper TTS voice"`.
+ * @returns The value, narrowed to exclude `NotGiven` and `null`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ * @throws Error If `value` is `null` or an empty string (upstream: ValueError).
+ */
+export declare function requireGiven<T>(value: T | null | undefined | NotGiven, what: string): T;
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/types.js

@@ -0,0 +1,108 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/types.py
+/**
+ * Types shared across Pipecat, independent of any provider SDK.
+ *
+ * The `NOT_GIVEN` sentinel lives here so that settings, contexts and anything
+ * else needing "this value was not provided" share one meaning. Provider SDKs
+ * ship their own equivalents; those belong to the SDK and are translated at the
+ * adapter boundary rather than used inside Pipecat.
+ */
+/**
+ * Sentinel type meaning "this value was not provided".
+ *
+ * Distinct from `null`, which is a meaningful value in most of the places
+ * this is used (typically "this service doesn't support this field").
+ * `NOT_GIVEN` is the singleton instance; test for it with `isGiven()`
+ * rather than comparing directly.
+ *
+ * DIVERGENCE: upstream makes the sentinel falsy (`__bool__` returns False) so
+ * `value or default` treats a missing value as absent. JavaScript objects are
+ * always truthy, so use `isGiven(value) ? value : fallback` instead.
+ */
+export class NotGiven {
+    static #instance = null;
+    /** Return the singleton instance, creating it on first use. */
+    constructor() {
+        if (NotGiven.#instance !== null) {
+            // biome-ignore lint/correctness/noConstructorReturn: singleton, as upstream's __new__.
+            return NotGiven.#instance;
+        }
+        NotGiven.#instance = this;
+    }
+    /** Return the sentinel's name. */
+    toString() {
+        return "NOT_GIVEN";
+    }
+    toJSON() {
+        return "NOT_GIVEN";
+    }
+}
+/** Singleton sentinel meaning "this value was not provided". */
+export const NOT_GIVEN = new NotGiven();
+/**
+ * Check whether a value was explicitly provided.
+ *
+ * Also acts as a type guard: inside a true branch, the value is narrowed to
+ * exclude `NotGiven` (e.g. `string | null | NotGiven` becomes `string | null`).
+ *
+ * @example
+ * if (isGiven(delta.voice)) {
+ *   // caller wants to change the voice
+ * }
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is anything other than `NOT_GIVEN`.
+ */
+export function isGiven(value) {
+    return !(value instanceof NotGiven);
+}
+/**
+ * Extract a value that must have been provided.
+ *
+ * Intended for reads where `NOT_GIVEN` should never appear, such as a
+ * store-mode settings object (see `services/settings`). Narrows away
+ * `NotGiven` at the type level and throws at runtime if that invariant is
+ * violated.
+ *
+ * @example
+ * const resolvedModel = assertGiven(this._settings.model); // narrowed string | null
+ *
+ * @param value The value to extract.
+ * @returns The value, narrowed to exclude `NotGiven`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ */
+export function assertGiven(value) {
+    if (!isGiven(value)) {
+        throw new Error("Expected a value, got NOT_GIVEN");
+    }
+    return value;
+}
+/**
+ * Extract a value that must have been provided and must not be empty.
+ *
+ * Like `assertGiven()`, but also rejects `null` (and `undefined`) and the
+ * empty string, which is what an unset or blank environment variable
+ * produces. Use it for settings a service cannot work without, such as a
+ * local model or voice that no provider will validate on its behalf.
+ *
+ * @example
+ * const voice = requireGiven(this._settings.voice, "Piper TTS voice"); // narrowed string
+ *
+ * @param value The value to extract.
+ * @param what How to name the value in the error, e.g. `"Piper TTS voice"`.
+ * @returns The value, narrowed to exclude `NotGiven` and `null`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ * @throws Error If `value` is `null` or an empty string (upstream: ValueError).
+ */
+export function requireGiven(value, what) {
+    const given = assertGiven(value);
+    if (given === null || given === undefined || given === "") {
+        throw new Error(`${what} must be specified`);
+    }
+    return given;
+}
+//# sourceMappingURL=types.js.map

package/dist/utils/utils.d.ts

@@ -0,0 +1,5 @@
+/** Generate a unique id for an object. */
+export declare function objId(): number;
+/** Generate a unique count for an object based on its class name. */
+export declare function objCount(obj: object): number;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils/utils.js

@@ -0,0 +1,22 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/utils.py
+/**
+ * Utility functions for object identification and counting.
+ */
+const counts = new Map();
+let nextId = 0;
+/** Generate a unique id for an object. */
+export function objId() {
+    return nextId++;
+}
+/** Generate a unique count for an object based on its class name. */
+export function objCount(obj) {
+    const name = obj.constructor.name;
+    const count = counts.get(name) ?? 0;
+    counts.set(name, count + 1);
+    return count;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils/yaml.d.ts

@@ -0,0 +1,64 @@
+/**
+ * YAML loading helpers shared across Pipecat's YAML-based configuration.
+ *
+ * The main helper is `includeLoader`, which builds a loader class that
+ * understands an `!include <relative-path>` tag so a document can pull in
+ * other files:
+ *
+ * ```yaml
+ * judge: !include judge_audio.yaml
+ * task_messages: !include prompts/greeting.yaml
+ * ```
+ *
+ * Include paths are not confined to the base directory; `..` and absolute
+ * paths reach anywhere the process can read. Use these loaders only on
+ * trusted documents.
+ *
+ * Not ported yet: Upstream builds on PyYAML loader classes and reads
+ * included files from disk. Core takes no YAML dependency and has no
+ * filesystem access (Workers), so only the interface is here; both functions
+ * throw until a YAML parser and file reader are wired in.
+ */
+/** A YAML node, as handed to a constructor. */
+export interface YamlNode {
+    /** Whether the node is a scalar (as opposed to a sequence or mapping). */
+    readonly isScalar: boolean;
+    /** The scalar value, for scalar nodes. */
+    readonly value?: unknown;
+}
+/** A tag constructor registered on a loader class. */
+export type YamlConstructor = (loader: unknown, node: YamlNode) => unknown;
+/** The loader-class shape the helpers work with (a `yaml.SafeLoader` subclass upstream). */
+export interface YamlLoaderClass {
+    /** Register a constructor for a tag on this loader class. */
+    addConstructor(tag: string, fn: YamlConstructor): void;
+}
+/**
+ * Register an `!include <relative-path>` constructor on `loaderClass`.
+ *
+ * Included files load with the same loader class, so nested includes work and
+ * scalars get the same resolver treatment as the top-level document. Paths
+ * resolve against `baseDir` and may reach outside it.
+ *
+ * This mutates `loaderClass`. Register on a private subclass rather than on
+ * the base loader itself so the constructor has no global side effects;
+ * `includeLoader` does that for you.
+ *
+ * @param loaderClass The loader class to register the constructor on.
+ * @param baseDir Directory that `!include` paths resolve against.
+ */
+export declare function addIncludeConstructor(_loaderClass: YamlLoaderClass, _baseDir: string): void;
+/**
+ * Build a loader class that resolves `!include` relative to `baseDir`.
+ *
+ * Returns a fresh subclass of `base` with the include constructor registered,
+ * so `base` itself is left untouched.
+ *
+ * @param baseDir Directory that `!include` paths resolve against, typically
+ *   the directory of the document being loaded.
+ * @param base Loader class to subclass. Defaults to the safe loader; pass a
+ *   custom one to keep its resolvers and constructors.
+ * @returns A loader class to load documents with.
+ */
+export declare function includeLoader(_baseDir: string, _base?: YamlLoaderClass): YamlLoaderClass;
+//# sourceMappingURL=yaml.d.ts.map

package/dist/utils/yaml.js

@@ -0,0 +1,41 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/yaml.py
+function notPorted(name) {
+    throw new Error(`pipecat.utils.yaml.${name}: not ported yet (needs a YAML parser)`);
+}
+/**
+ * Register an `!include <relative-path>` constructor on `loaderClass`.
+ *
+ * Included files load with the same loader class, so nested includes work and
+ * scalars get the same resolver treatment as the top-level document. Paths
+ * resolve against `baseDir` and may reach outside it.
+ *
+ * This mutates `loaderClass`. Register on a private subclass rather than on
+ * the base loader itself so the constructor has no global side effects;
+ * `includeLoader` does that for you.
+ *
+ * @param loaderClass The loader class to register the constructor on.
+ * @param baseDir Directory that `!include` paths resolve against.
+ */
+export function addIncludeConstructor(_loaderClass, _baseDir) {
+    notPorted("add_include_constructor");
+}
+/**
+ * Build a loader class that resolves `!include` relative to `baseDir`.
+ *
+ * Returns a fresh subclass of `base` with the include constructor registered,
+ * so `base` itself is left untouched.
+ *
+ * @param baseDir Directory that `!include` paths resolve against, typically
+ *   the directory of the document being loaded.
+ * @param base Loader class to subclass. Defaults to the safe loader; pass a
+ *   custom one to keep its resolvers and constructors.
+ * @returns A loader class to load documents with.
+ */
+export function includeLoader(_baseDir, _base) {
+    return notPorted("include_loader");
+}
+//# sourceMappingURL=yaml.js.map

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** The version of @pipedog/core (all @pipedog packages share it). */
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,7 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Generated by tools/release/sync-version.ts from package.json; do not edit.
+/** The version of @pipedog/core (all @pipedog packages share it). */
+export const VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map