libretto 0.3.0 → 0.3.1

package/dist/shared/logger/logger.cjs

@@ -0,0 +1,232 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var logger_exports = {};
+__export(logger_exports, {
+  Logger: () => Logger,
+  defaultLogger: () => defaultLogger
+});
+module.exports = __toCommonJS(logger_exports);
+function generateId() {
+  return Math.random().toString(36).substring(2, 15);
+}
+const defaultLogger = {
+  info(event, data) {
+    console.log(`[INFO] ${event}`, data ?? "");
+  },
+  warn(event, data) {
+    console.warn(`[WARN] ${event}`, data ?? "");
+  },
+  error(event, data) {
+    console.error(`[ERROR] ${event}`, data ?? "");
+  }
+};
+const sinkLifecycleState = /* @__PURE__ */ new WeakMap();
+function getSinkLifecycleState(sink) {
+  const existingState = sinkLifecycleState.get(sink);
+  if (existingState) {
+    return existingState;
+  }
+  const initialState = { closed: false };
+  sinkLifecycleState.set(sink, initialState);
+  return initialState;
+}
+function isSinkClosedOrClosing(sink) {
+  const state = sinkLifecycleState.get(sink);
+  return Boolean(state?.closed || state?.closing);
+}
+async function closeSinkOnce(sink) {
+  if (!sink.close) {
+    return;
+  }
+  const state = getSinkLifecycleState(sink);
+  if (state.closed) {
+    return;
+  }
+  if (state.closing) {
+    return state.closing;
+  }
+  state.closing = (async () => {
+    try {
+      await sink.close?.();
+    } catch {
+    } finally {
+      state.closed = true;
+      state.closing = void 0;
+    }
+  })();
+  return state.closing;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function removeUndefined(data) {
+  if (typeof data === "object" && data !== null) {
+    return Object.fromEntries(
+      Object.entries(data).filter(([_, value]) => value !== void 0)
+    );
+  }
+  return data;
+}
+class Logger {
+  constructor(scopes = [], sinks = [], scopeData = {}) {
+    this.scopes = scopes;
+    this.sinks = sinks;
+    this.scopeData = scopeData;
+    this.prefix = scopes.join(".");
+  }
+  prefix;
+  entry(entry) {
+    this.sinks.forEach((sink) => {
+      if (isSinkClosedOrClosing(sink)) {
+        return;
+      }
+      sink.write({
+        id: generateId(),
+        scope: this.prefix,
+        level: entry.level,
+        event: entry.event,
+        data: removeUndefined({ ...this.scopeData, ...entry.data }),
+        options: entry.options
+      });
+    });
+  }
+  log(event, data, options) {
+    this.entry({ level: "log", event, data, options });
+  }
+  error(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "error",
+      event,
+      data,
+      options
+    });
+    if (dataOrError instanceof Error) {
+      return dataOrError;
+    }
+    if (isObject(dataOrError) && dataOrError.error instanceof Error) {
+      return dataOrError.error;
+    }
+    let message = event;
+    if (data !== void 0) {
+      try {
+        message += "\n" + JSON.stringify(data, void 0, 2);
+      } catch {
+        message += "\n[Unserializable error data]";
+      }
+    }
+    return new Error(message);
+  }
+  warn(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "warn",
+      event,
+      data,
+      options
+    });
+  }
+  info(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "info",
+      event,
+      data,
+      options
+    });
+  }
+  withScope(scope, context = {}) {
+    return new Logger([...this.scopes, scope], this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withContext(context) {
+    return new Logger(this.scopes, this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withSink(sink) {
+    return new Logger(this.scopes, [...this.sinks, sink]);
+  }
+  async flush() {
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      if (isSinkClosedOrClosing(sink)) continue;
+      try {
+        await sink.flush?.();
+      } catch {
+      }
+    }
+  }
+  async close() {
+    await this.flush();
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      await closeSinkOnce(sink);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Logger,
+  defaultLogger
+});

package/dist/shared/logger/logger.d.cts

@@ -0,0 +1,86 @@
+type LogOptions = {
+    timestamp?: Date;
+};
+/**
+ * Minimal logger interface accepted by public-facing runtime functions.
+ * Any logger with info/warn/error methods satisfies this — no need to
+ * implement withScope, withContext, flush, etc.
+ */
+type MinimalLogger = {
+    info: (event: string, data?: any) => void;
+    warn: (event: string, data?: any) => void;
+    error: (event: string, data?: any) => any;
+};
+/** Default console logger used when callers omit the logger option. */
+declare const defaultLogger: MinimalLogger;
+type LoggerApi = {
+    log: (event: string, data?: Record<string, any>, options?: LogOptions) => void;
+    /**
+     * Logs an error and returns an Error object that can be thrown
+     *
+     * either pass in an Error directly as data or as { error: Error, ...other_data }
+     */
+    error: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => Error;
+    warn: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => void;
+    info: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => void;
+    /**
+     * Context passed in will be attached to all entries in this scope.
+     */
+    withScope: (scope: string, context?: Record<string, any>) => LoggerApi;
+    /**
+     * Context passed in will be attached to all entries.
+     */
+    withContext: (context: Record<string, any>) => LoggerApi;
+    /**
+     * Flushes all sinks in reverse order (most recently added first).
+     */
+    flush: () => Promise<void>;
+};
+type LoggerSink = {
+    write: (args: {
+        id: string;
+        scope: string;
+        level: "log" | "error" | "warn" | "info";
+        event: string;
+        data: Record<string, any>;
+        options?: LogOptions;
+    }) => void;
+    flush?: () => Promise<void>;
+    close?: () => Promise<void>;
+};
+declare class Logger implements LoggerApi {
+    private readonly scopes;
+    private readonly sinks;
+    private readonly scopeData;
+    private readonly prefix;
+    constructor(scopes?: string[], sinks?: LoggerSink[], scopeData?: Record<string, any>);
+    entry(entry: {
+        level: "log" | "error" | "warn" | "info";
+        event: string;
+        data?: Record<string, any>;
+        options?: LogOptions;
+    }): void;
+    log(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    error(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): Error;
+    warn(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
+    info(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
+    withScope(scope: string, context?: Record<string, any>): LoggerApi;
+    withContext(context: Record<string, any>): LoggerApi;
+    withSink(sink: LoggerSink): Logger;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+
+export { type LogOptions, Logger, type LoggerApi, type LoggerSink, type MinimalLogger, defaultLogger };

package/dist/shared/logger/logger.d.ts

@@ -0,0 +1,86 @@
+type LogOptions = {
+    timestamp?: Date;
+};
+/**
+ * Minimal logger interface accepted by public-facing runtime functions.
+ * Any logger with info/warn/error methods satisfies this — no need to
+ * implement withScope, withContext, flush, etc.
+ */
+type MinimalLogger = {
+    info: (event: string, data?: any) => void;
+    warn: (event: string, data?: any) => void;
+    error: (event: string, data?: any) => any;
+};
+/** Default console logger used when callers omit the logger option. */
+declare const defaultLogger: MinimalLogger;
+type LoggerApi = {
+    log: (event: string, data?: Record<string, any>, options?: LogOptions) => void;
+    /**
+     * Logs an error and returns an Error object that can be thrown
+     *
+     * either pass in an Error directly as data or as { error: Error, ...other_data }
+     */
+    error: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => Error;
+    warn: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => void;
+    info: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => void;
+    /**
+     * Context passed in will be attached to all entries in this scope.
+     */
+    withScope: (scope: string, context?: Record<string, any>) => LoggerApi;
+    /**
+     * Context passed in will be attached to all entries.
+     */
+    withContext: (context: Record<string, any>) => LoggerApi;
+    /**
+     * Flushes all sinks in reverse order (most recently added first).
+     */
+    flush: () => Promise<void>;
+};
+type LoggerSink = {
+    write: (args: {
+        id: string;
+        scope: string;
+        level: "log" | "error" | "warn" | "info";
+        event: string;
+        data: Record<string, any>;
+        options?: LogOptions;
+    }) => void;
+    flush?: () => Promise<void>;
+    close?: () => Promise<void>;
+};
+declare class Logger implements LoggerApi {
+    private readonly scopes;
+    private readonly sinks;
+    private readonly scopeData;
+    private readonly prefix;
+    constructor(scopes?: string[], sinks?: LoggerSink[], scopeData?: Record<string, any>);
+    entry(entry: {
+        level: "log" | "error" | "warn" | "info";
+        event: string;
+        data?: Record<string, any>;
+        options?: LogOptions;
+    }): void;
+    log(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    error(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): Error;
+    warn(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
+    info(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
+    withScope(scope: string, context?: Record<string, any>): LoggerApi;
+    withContext(context: Record<string, any>): LoggerApi;
+    withSink(sink: LoggerSink): Logger;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+
+export { type LogOptions, Logger, type LoggerApi, type LoggerSink, type MinimalLogger, defaultLogger };

package/dist/shared/logger/logger.js

@@ -0,0 +1,207 @@
+function generateId() {
+  return Math.random().toString(36).substring(2, 15);
+}
+const defaultLogger = {
+  info(event, data) {
+    console.log(`[INFO] ${event}`, data ?? "");
+  },
+  warn(event, data) {
+    console.warn(`[WARN] ${event}`, data ?? "");
+  },
+  error(event, data) {
+    console.error(`[ERROR] ${event}`, data ?? "");
+  }
+};
+const sinkLifecycleState = /* @__PURE__ */ new WeakMap();
+function getSinkLifecycleState(sink) {
+  const existingState = sinkLifecycleState.get(sink);
+  if (existingState) {
+    return existingState;
+  }
+  const initialState = { closed: false };
+  sinkLifecycleState.set(sink, initialState);
+  return initialState;
+}
+function isSinkClosedOrClosing(sink) {
+  const state = sinkLifecycleState.get(sink);
+  return Boolean(state?.closed || state?.closing);
+}
+async function closeSinkOnce(sink) {
+  if (!sink.close) {
+    return;
+  }
+  const state = getSinkLifecycleState(sink);
+  if (state.closed) {
+    return;
+  }
+  if (state.closing) {
+    return state.closing;
+  }
+  state.closing = (async () => {
+    try {
+      await sink.close?.();
+    } catch {
+    } finally {
+      state.closed = true;
+      state.closing = void 0;
+    }
+  })();
+  return state.closing;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function removeUndefined(data) {
+  if (typeof data === "object" && data !== null) {
+    return Object.fromEntries(
+      Object.entries(data).filter(([_, value]) => value !== void 0)
+    );
+  }
+  return data;
+}
+class Logger {
+  constructor(scopes = [], sinks = [], scopeData = {}) {
+    this.scopes = scopes;
+    this.sinks = sinks;
+    this.scopeData = scopeData;
+    this.prefix = scopes.join(".");
+  }
+  prefix;
+  entry(entry) {
+    this.sinks.forEach((sink) => {
+      if (isSinkClosedOrClosing(sink)) {
+        return;
+      }
+      sink.write({
+        id: generateId(),
+        scope: this.prefix,
+        level: entry.level,
+        event: entry.event,
+        data: removeUndefined({ ...this.scopeData, ...entry.data }),
+        options: entry.options
+      });
+    });
+  }
+  log(event, data, options) {
+    this.entry({ level: "log", event, data, options });
+  }
+  error(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "error",
+      event,
+      data,
+      options
+    });
+    if (dataOrError instanceof Error) {
+      return dataOrError;
+    }
+    if (isObject(dataOrError) && dataOrError.error instanceof Error) {
+      return dataOrError.error;
+    }
+    let message = event;
+    if (data !== void 0) {
+      try {
+        message += "\n" + JSON.stringify(data, void 0, 2);
+      } catch {
+        message += "\n[Unserializable error data]";
+      }
+    }
+    return new Error(message);
+  }
+  warn(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "warn",
+      event,
+      data,
+      options
+    });
+  }
+  info(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "info",
+      event,
+      data,
+      options
+    });
+  }
+  withScope(scope, context = {}) {
+    return new Logger([...this.scopes, scope], this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withContext(context) {
+    return new Logger(this.scopes, this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withSink(sink) {
+    return new Logger(this.scopes, [...this.sinks, sink]);
+  }
+  async flush() {
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      if (isSinkClosedOrClosing(sink)) continue;
+      try {
+        await sink.flush?.();
+      } catch {
+      }
+    }
+  }
+  async close() {
+    await this.flush();
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      await closeSinkOnce(sink);
+    }
+  }
+}
+export {
+  Logger,
+  defaultLogger
+};