@pipedog/core 0.0.0 → 0.1.0

package/dist/utils/shared.js

@@ -0,0 +1,136 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/shared.py
+/**
+ * Decorators for operations on a resource shared by several owners.
+ *
+ * An input and an output transport share a single client, so both set it up,
+ * both join its room, and both tear it down. Processors are set up and cleaned
+ * up concurrently, so those calls overlap.
+ *
+ * Decorate the paired operations with `acquires` and `releases` and the work
+ * runs once: the first owner to acquire runs the body while the rest wait for
+ * it, and only the last owner to release runs the undo.
+ *
+ * The returned decorators work both as standard (TC39) method decorators and
+ * as plain functions, since runtimes that strip types (Node) do not run
+ * decorator syntax:
+ *
+ * @example
+ * class Client {
+ *   async setup(): Promise<void> { ... }
+ *   async cleanup(): Promise<void> { ... }
+ *   static {
+ *     this.prototype.setup = acquires("client")(this.prototype.setup);
+ *     this.prototype.cleanup = releases("client")(this.prototype.cleanup);
+ *   }
+ * }
+ */
+import { Lock } from "@pipedog/asyncio";
+/** How many owners hold a resource, and the lock serializing them. */
+class SharedResource {
+    owners = 0;
+    lock = new Lock();
+    // What acquiring raised, if it did, so later owners fail the same way.
+    error = null;
+    hasError = false;
+}
+// Upstream keeps the state in the instance's `__dict__`; a WeakMap keeps it
+// per instance without touching the object.
+const RESOURCES = new WeakMap();
+/**
+ * Get the named resource's state, creating it on first use.
+ *
+ * The state lives with the instance so a class doesn't need to initialize it,
+ * and so two instances of the same class count their owners separately.
+ */
+function sharedResource(obj, name) {
+    let resources = RESOURCES.get(obj);
+    if (!resources) {
+        resources = new Map();
+        RESOURCES.set(obj, resources);
+    }
+    let resource = resources.get(name);
+    if (!resource) {
+        resource = new SharedResource();
+        resources.set(name, resource);
+    }
+    return resource;
+}
+/**
+ * Run the decorated method for the first owner to acquire `name`.
+ *
+ * Owners that arrive while the first is still running wait for it to finish,
+ * so no caller continues against a half-built resource. Later owners return
+ * `null` without running the method again.
+ *
+ * A method that throws leaves the resource unbuilt, and every owner of it is
+ * told: the error is re-thrown to each one that arrives later, rather than the
+ * method being attempted again. So the owners of a resource share its verdict,
+ * and a pair of processors sharing a client either both come up or both fail.
+ *
+ * Note: the lock is not reentrant, so a method must not call another method
+ * that acquires the same resource.
+ *
+ * @param name The resource being acquired. Names are per instance, so paired
+ *   operations on the same object (e.g. `setup`/`cleanup` and `join`/`leave`)
+ *   count their owners separately.
+ */
+export function acquires(name) {
+    return function decorator(func, _context) {
+        return async function wrapper(...args) {
+            const resource = sharedResource(this, name);
+            return await resource.lock.run(async () => {
+                if (resource.hasError) {
+                    throw resource.error;
+                }
+                resource.owners += 1;
+                if (resource.owners === 1) {
+                    try {
+                        return await func.apply(this, args);
+                    }
+                    catch (e) {
+                        // Nothing was built, so nothing is owned and nothing is released
+                        // later. Upstream catches BaseException, so cancellation counts too.
+                        resource.owners -= 1;
+                        resource.error = e;
+                        resource.hasError = true;
+                        throw e;
+                    }
+                }
+                return null;
+            });
+        };
+    };
+}
+/**
+ * Run the decorated method for the last owner to release `name`.
+ *
+ * Every other owner returns `null`, as does a release that no acquire
+ * matched.
+ *
+ * Note: the lock is not reentrant, so a method must not call another method
+ * that releases the same resource.
+ *
+ * @param name The resource being released, matching the `acquires` name.
+ */
+export function releases(name) {
+    return function decorator(func, _context) {
+        return async function wrapper(...args) {
+            const resource = sharedResource(this, name);
+            return await resource.lock.run(async () => {
+                if (resource.owners === 0) {
+                    return null;
+                }
+                resource.owners -= 1;
+                if (resource.owners === 0) {
+                    return await func.apply(this, args);
+                }
+                return null;
+            });
+        };
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/utils/startup.d.ts

@@ -0,0 +1,17 @@
+/** Absolute paths of the files listed in `PIPECAT_SETUP_FILES`. */
+export declare function _setupFilePaths(): string[];
+export interface RunSetupHookOptions {
+    /** Object passed to the hook function. */
+    target: unknown;
+    /** Name of the async function to call in each setup file (e.g. `"setup_worker_runner"`). */
+    functionName: string;
+}
+/**
+ * Run `functionName(target)` from every `PIPECAT_SETUP_FILES` module.
+ *
+ * @param options.target Object passed to the hook function.
+ * @param options.functionName Name of the async function to call in each
+ *   setup file. Its camelCase spelling is accepted too.
+ */
+export declare function runSetupHook(options: RunSetupHookOptions): Promise<void>;
+//# sourceMappingURL=startup.d.ts.map

package/dist/utils/startup.js

@@ -0,0 +1,130 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/startup.py
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Shared loader for `PIPECAT_SETUP_FILES` hooks.
+ *
+ * Each file listed in the `PIPECAT_SETUP_FILES` environment variable (separated
+ * by the platform path separator) may export one or both of the following
+ * async functions:
+ *
+ * - `setup_worker_runner(runner)` — invoked once per `WorkerRunner` before its
+ *   spawned workers start.
+ * - `setup_pipeline_worker(worker)` — invoked once per `PipelineWorker` while
+ *   the worker sets up its pipeline.
+ *
+ * The camelCase spelling (`setupWorkerRunner`, `setupPipelineWorker`) is
+ * accepted too.
+ *
+ * Setup files are imported at most once per process; module-level state (for
+ * example, a shared debugger instance referenced by both hooks) is preserved
+ * across hook invocations.
+ *
+ * Porting notes: setup files are ES modules loaded with dynamic `import()`, so
+ * this works where the runtime can import from the file system (Bun, Node,
+ * Deno). On runtimes without a file system or environment variables
+ * (Cloudflare Workers) `PIPECAT_SETUP_FILES` is simply unset. The deprecated
+ * `setup_pipeline_task` fallback name is not ported.
+ */
+import { rethrowIfCancelled } from "@pipedog/asyncio";
+import { logger } from "./logger.js";
+const moduleCache = new Map();
+function proc() {
+    return globalThis.process;
+}
+function pathSeparator() {
+    return proc()?.platform === "win32" ? ";" : ":";
+}
+/** Resolve a setup file path to an absolute path (URLs are kept as-is). */
+function resolvePath(path) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
+        return new URL(path).href;
+    const isWindowsAbsolute = /^[a-zA-Z]:[\\/]/.test(path);
+    if (path.startsWith("/") || isWindowsAbsolute) {
+        return fileUrlToPath(new URL(`file://${isWindowsAbsolute ? "/" : ""}${path.replaceAll("\\", "/")}`));
+    }
+    const cwd = (proc()?.cwd?.() ?? "/").replaceAll("\\", "/");
+    const base = cwd.startsWith("/") ? `file://${cwd}/` : `file:///${cwd}/`;
+    return fileUrlToPath(new URL(path.replaceAll("\\", "/"), base));
+}
+/** Convert a normalized `file:` URL back to a file system path. */
+function fileUrlToPath(url) {
+    const path = decodeURIComponent(url.pathname);
+    return /^\/[a-zA-Z]:\//.test(path) ? path.slice(1) : path;
+}
+/** Convert a resolved setup file path to a URL usable with `import()`. */
+function importUrl(path) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
+        return path;
+    const url = new URL("file://");
+    url.pathname = path.startsWith("/") ? path : `/${path}`;
+    return url.href;
+}
+/** Absolute paths of the files listed in `PIPECAT_SETUP_FILES`. */
+export function _setupFilePaths() {
+    return (proc()?.env?.PIPECAT_SETUP_FILES ?? "")
+        .split(pathSeparator())
+        .filter((f) => f)
+        .map((f) => resolvePath(f));
+}
+async function loadModule(path) {
+    const cached = moduleCache.get(path);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let module;
+    try {
+        module = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ importUrl(path))));
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+        logger.error(`error loading setup file ${path}: ${e instanceof Error ? e.message : e}`);
+        return null;
+    }
+    moduleCache.set(path, module);
+    return module;
+}
+function camelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Run `functionName(target)` from every `PIPECAT_SETUP_FILES` module.
+ *
+ * @param options.target Object passed to the hook function.
+ * @param options.functionName Name of the async function to call in each
+ *   setup file. Its camelCase spelling is accepted too.
+ */
+export async function runSetupHook(options) {
+    const { target, functionName } = options;
+    for (const path of _setupFilePaths()) {
+        const module = await loadModule(path);
+        if (module === null) {
+            continue;
+        }
+        try {
+            const fn = module[functionName] ?? module[camelCase(functionName)];
+            if (typeof fn === "function") {
+                logger.debug(`${target} running ${functionName} from ${path}`);
+                await fn(target);
+            }
+            else {
+                logger.warning(`${target} setup file ${path} has no ${functionName} function`);
+            }
+        }
+        catch (e) {
+            rethrowIfCancelled(e);
+            logger.error(`${target} error running ${functionName} from ${path}: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+}
+//# sourceMappingURL=startup.js.map

package/dist/utils/string.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Split `text` into spans, like sentencex's `segment(language, text)`.
+ *
+ * The spans must concatenate back to `text`; each span is a sentence with
+ * whatever whitespace the segmenter attaches to it.
+ */
+export type SentenceSegmenter = (language: string, text: string) => Iterable<string>;
+/**
+ * Normalize a language code for sentencex's language fallback map.
+ *
+ * @param language Language code, optionally with a region. null, empty, and
+ *   automatic language selections use English.
+ * @returns A lowercase base language code. The segmenter resolves unsupported codes.
+ */
+export declare function resolveSentenceTokenizerLanguage(language: string | null | undefined): string;
+/** An alternative segmenter: `Intl.Segmenter` plus abbreviation merging. */
+export declare const intlSentenceSegmenter: SentenceSegmenter;
+/** The default segmenter: sentencex, as upstream. */
+export declare const sentencexSegmenter: SentenceSegmenter;
+/**
+ * Install the sentence segmenter used for sentence boundary detection (for
+ * example `intlSentenceSegmenter`). Pass `null` to restore the default,
+ * sentencex.
+ */
+export declare function setSentenceSegmenter(segmenter: SentenceSegmenter | null): void;
+export declare const SENTENCE_ENDING_PUNCTUATION: ReadonlySet<string>;
+export declare const UNAMBIGUOUS_SENTENCE_ENDING_PUNCTUATION: ReadonlySet<string>;
+export type StartEndTags = readonly [string, string];
+/**
+ * Replace occurrences of a substring within a matched section of text.
+ *
+ * @param text The input text in which replacements will be made.
+ * @param match A regex match representing the section of text to modify.
+ * @param old The substring to be replaced.
+ * @param replacement The substring to replace `old` with.
+ * @returns The modified text with the specified replacements made within the matched section.
+ */
+export declare function replaceMatch(text: string, match: RegExpExecArray | RegExpMatchArray, old: string, replacement: string): string;
+/**
+ * Find the position of the end of a sentence in the provided text.
+ *
+ * This function uses the sentence tokenizer to detect sentence boundaries in
+ * the input text, combined with punctuation verification to ensure that
+ * single tokens without proper sentence endings aren't considered complete
+ * sentences.
+ *
+ * @param text The input text in which to find the end of the sentence.
+ * @param options.language Language code. Defaults to English.
+ * @returns The position of the end of the sentence if found, otherwise 0.
+ */
+export declare function matchEndofsentence(text: string, options?: {
+    language?: string | null;
+}): number;
+/**
+ * Parse text to identify start and end tag pairs.
+ *
+ * If a start tag was previously found (i.e., currentTag is valid), wait for
+ * the corresponding end tag. Otherwise, wait for a start tag.
+ *
+ * This function returns the index in the text where parsing should continue
+ * in the next call and the current or new tags.
+ *
+ * @param text The text to be parsed.
+ * @param tags List of tuples containing start and end tags.
+ * @param currentTag The currently active tags, if any.
+ * @param currentTagIndex The current index in the text.
+ * @returns A tuple containing null or the current tag and the index of the text.
+ */
+export declare function parseStartEndTags(text: string, tags: readonly StartEndTags[], currentTag: StartEndTags | null, currentTagIndex: number): [StartEndTags | null, number];
+/**
+ * Find the length of the longest suffix of text that is a proper prefix of a candidate.
+ *
+ * Used to detect a delimiter (e.g., an XML-style start tag) that has been
+ * split across two text chunks: the trailing partial delimiter can be held
+ * back from output until the next chunk completes it, rather than being
+ * flushed as plain text and losing the delimiter.
+ *
+ * @param text The text to check for a trailing partial match.
+ * @param candidates Full strings to match a proper prefix of against the end of text.
+ * @returns The length of the longest matching suffix, or 0 if no candidate has a
+ *   proper prefix matching the end of text.
+ */
+export declare function longestTrailingPartialMatch(text: string, candidates: readonly string[]): number;
+export interface TextPartForConcatenationOptions {
+    /** The text content. */
+    text: string;
+    /** Whether any necessary inter-frame (leading/trailing) spaces are already included in the text. */
+    includesInterPartSpaces: boolean;
+}
+/**
+ * Class representing a part of text for concatenation with `concatenateAggregatedText`.
+ *
+ * - `text`: The text content.
+ * - `includesInterPartSpaces`: Whether any necessary inter-frame
+ *   (leading/trailing) spaces are already included in the text.
+ */
+export declare class TextPartForConcatenation {
+    text: string;
+    includesInterPartSpaces: boolean;
+    constructor(options: TextPartForConcatenationOptions);
+    toString(): string;
+}
+/**
+ * Concatenate a list of text parts into a single string.
+ *
+ * This function joins the provided list of text parts into a single string,
+ * taking into account whether or not the parts already contain spacing.
+ *
+ * This function is useful for aggregating text segments received from LLMs or
+ * transcription services.
+ *
+ * @param textParts A list of text parts to concatenate.
+ * @returns A single concatenated string.
+ */
+export declare function concatenateAggregatedText(textParts: readonly TextPartForConcatenation[]): string;
+//# sourceMappingURL=string.d.ts.map