logquill 0.3.0 → 1.0.0

package/dist/winston.cjs

@@ -0,0 +1,108 @@
+'use strict';
+
+var Transport = require('winston-transport');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Transport__default = /*#__PURE__*/_interopDefault(Transport);
+
+// src/bridges/winston-transport.ts
+
+// src/core/levels.ts
+var Level = /* @__PURE__ */ ((Level2) => {
+  Level2[Level2["TRACE"] = 5] = "TRACE";
+  Level2[Level2["DEBUG"] = 10] = "DEBUG";
+  Level2[Level2["INFO"] = 20] = "INFO";
+  Level2[Level2["WARN"] = 30] = "WARN";
+  Level2[Level2["ERROR"] = 40] = "ERROR";
+  Level2[Level2["FATAL"] = 50] = "FATAL";
+  return Level2;
+})(Level || {});
+var NAME_TO_LEVEL = {
+  TRACE: 5 /* TRACE */,
+  DEBUG: 10 /* DEBUG */,
+  INFO: 20 /* INFO */,
+  WARN: 30 /* WARN */,
+  ERROR: 40 /* ERROR */,
+  FATAL: 50 /* FATAL */
+};
+function parseLevel(level) {
+  if (typeof level === "string") {
+    const parsed = NAME_TO_LEVEL[level.toUpperCase()];
+    if (parsed === void 0) {
+      throw new Error(`Unknown log level: ${level}`);
+    }
+    return parsed;
+  }
+  if (Level[level] === void 0) {
+    throw new Error(`Unknown log level: ${String(level)}`);
+  }
+  return level;
+}
+
+// src/bridges/level-dispatch.ts
+function callAtLevel(log, level, message, meta) {
+  switch (level) {
+    case 5 /* TRACE */:
+      log.trace(message, meta);
+      return;
+    case 10 /* DEBUG */:
+      log.debug(message, meta);
+      return;
+    case 20 /* INFO */:
+      log.info(message, meta);
+      return;
+    case 30 /* WARN */:
+      log.warn(message, meta);
+      return;
+    case 40 /* ERROR */:
+      log.error(message, meta);
+      return;
+    case 50 /* FATAL */:
+      log.fatal(message, meta);
+      return;
+  }
+}
+
+// src/bridges/winston-transport.ts
+var DEFAULT_WINSTON_LEVEL_MAP = {
+  error: 40 /* ERROR */,
+  warn: 30 /* WARN */,
+  info: 20 /* INFO */,
+  http: 20 /* INFO */,
+  verbose: 10 /* DEBUG */,
+  debug: 10 /* DEBUG */,
+  silly: 5 /* TRACE */
+};
+var LogQuillWinstonTransport = class extends Transport__default.default {
+  target;
+  levelMap;
+  constructor(logquillLogger, options = {}) {
+    const { levelMap, ...transportOptions } = options;
+    super(transportOptions);
+    this.target = logquillLogger;
+    this.levelMap = levelMap ?? DEFAULT_WINSTON_LEVEL_MAP;
+  }
+  /** winston-transport's own write hook — called by winston for every entry that reaches this transport. */
+  log(info, callback) {
+    setImmediate(() => {
+      this.emit("logged", info);
+    });
+    const entry = info;
+    const winstonLevel = typeof entry.level === "string" ? entry.level : "info";
+    const message = typeof entry.message === "string" ? entry.message : String(entry.message);
+    const meta = {};
+    for (const key of Object.keys(entry)) {
+      if (key !== "level" && key !== "message") {
+        meta[key] = entry[key];
+      }
+    }
+    callAtLevel(this.target, parseLevel(this.levelMap[winstonLevel] ?? 20 /* INFO */), message, meta);
+    callback();
+  }
+};
+
+exports.DEFAULT_WINSTON_LEVEL_MAP = DEFAULT_WINSTON_LEVEL_MAP;
+exports.LogQuillWinstonTransport = LogQuillWinstonTransport;
+//# sourceMappingURL=winston.cjs.map
+//# sourceMappingURL=winston.cjs.map

package/dist/winston.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/levels.ts","../src/bridges/level-dispatch.ts","../src/bridges/winston-transport.ts"],"names":["Level","Transport"],"mappings":"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","file":"winston.cjs","sourcesContent":["/** Log levels, shared by name and numeric weight with the logquill-python contract. */\nexport enum Level {\n  /** Finest-grained diagnostic detail. */\n  TRACE = 5,\n  /** Diagnostic detail useful in development. */\n  DEBUG = 10,\n  /** Notable events during normal operation. */\n  INFO = 20,\n  /** Something unexpected, but not (yet) an error. */\n  WARN = 30,\n  /** An error that didn't necessarily stop the operation. */\n  ERROR = 40,\n  /** An error that precedes an unrecoverable failure. */\n  FATAL = 50,\n}\n\nconst NAME_TO_LEVEL: Readonly<Record<string, Level>> = {\n  TRACE: Level.TRACE,\n  DEBUG: Level.DEBUG,\n  INFO: Level.INFO,\n  WARN: Level.WARN,\n  ERROR: Level.ERROR,\n  FATAL: Level.FATAL,\n};\n\n/** A level given as a `Level`, a level name (any case), or its numeric weight. */\nexport type LevelInput = Level | number | string;\n\n/** The level's name, e.g. `levelName(Level.INFO) === \"INFO\"`. */\nexport function levelName(level: Level): string {\n  return Level[level];\n}\n\n/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */\nexport function parseLevel(level: LevelInput): Level {\n  if (typeof level === \"string\") {\n    const parsed = NAME_TO_LEVEL[level.toUpperCase()];\n    if (parsed === undefined) {\n      throw new Error(`Unknown log level: ${level}`);\n    }\n    return parsed;\n  }\n  if (Level[level] === undefined) {\n    throw new Error(`Unknown log level: ${String(level)}`);\n  }\n  return level;\n}\n","import { Level } from \"../core/levels.js\";\nimport type { Logger } from \"../core/logger.js\";\n\n/** Calls the `Logger` method matching `level` — shared by every bridge that maps another library's numeric/string level onto ours. */\nexport function callAtLevel(\n  log: Logger,\n  level: Level,\n  message: string,\n  meta: Record<string, unknown>,\n): void {\n  switch (level) {\n    case Level.TRACE:\n      log.trace(message, meta);\n      return;\n    case Level.DEBUG:\n      log.debug(message, meta);\n      return;\n    case Level.INFO:\n      log.info(message, meta);\n      return;\n    case Level.WARN:\n      log.warn(message, meta);\n      return;\n    case Level.ERROR:\n      log.error(message, meta);\n      return;\n    case Level.FATAL:\n      log.fatal(message, meta);\n      return;\n  }\n}\n","import Transport from \"winston-transport\";\nimport { Level, parseLevel, type LevelInput } from \"../core/levels.js\";\nimport type { Logger } from \"../core/logger.js\";\nimport { callAtLevel } from \"./level-dispatch.js\";\n\n/** Maps a winston level name to a LogQuill level. */\nexport type WinstonLevelMap = Readonly<Record<string, LevelInput>>;\n\n/** winston's built-in `npm` levels (its default), mapped onto the closest LogQuill level. */\nexport const DEFAULT_WINSTON_LEVEL_MAP: WinstonLevelMap = {\n  error: Level.ERROR,\n  warn: Level.WARN,\n  info: Level.INFO,\n  http: Level.INFO,\n  verbose: Level.DEBUG,\n  debug: Level.DEBUG,\n  silly: Level.TRACE,\n};\n\n/** Options for {@link LogQuillWinstonTransport}, extending winston-transport's own `TransportStreamOptions` (`level`, etc.). */\nexport interface LogQuillWinstonTransportOptions extends Transport.TransportStreamOptions {\n  /** Overrides `DEFAULT_WINSTON_LEVEL_MAP` — useful for a winston logger configured with custom levels. An unmapped level falls back to `INFO`. */\n  levelMap?: WinstonLevelMap;\n}\n\n/**\n * A `winston-transport` `Transport`, so an existing `winston.createLogger()`\n * app can add a LogQuill `Logger` as one more destination with no call-site\n * changes: every `.info()/.warn()/...` call already going through winston\n * keeps working exactly as it does today, and now also flows through this\n * transport into every LogQuill `Transport`/`Plugin` attached to the given\n * `Logger` — handy for migrating incrementally rather than in one PR.\n *\n * ```ts\n * import winston from \"winston\";\n * import { Logger } from \"logquill\";\n * import { LogQuillWinstonTransport } from \"logquill/winston\";\n *\n * const logquill = new Logger(\"app\");\n * const winstonLogger = winston.createLogger({\n *   transports: [new LogQuillWinstonTransport(logquill)],\n * });\n *\n * winstonLogger.info(\"still works exactly as before\", { userId: 42 });\n * ```\n *\n * winston's own level filtering (its logger's configured `level`, and this\n * transport's own `level` option) runs first, same as any other winston\n * transport; whatever reaches this transport is then mapped onto a LogQuill\n * level via `levelMap` and re-filtered by the LogQuill `Logger`'s own\n * `level` — the stricter of the two wins.\n *\n * Ships from a **separate entry point**, `import ... from \"logquill/winston\"`\n * — not the main `\"logquill\"` import — for the same reason `LangChainAdapter`\n * does: it has to `extends Transport`, `winston-transport`'s own class, a\n * hard static import. Keeping it out of the main entry point means a plain\n * `import { Logger } from \"logquill\"` never requires `winston-transport` to\n * be installed. `winston-transport` is an optional peer dependency.\n */\nexport class LogQuillWinstonTransport extends Transport {\n  private readonly target: Logger;\n  private readonly levelMap: WinstonLevelMap;\n\n  constructor(logquillLogger: Logger, options: LogQuillWinstonTransportOptions = {}) {\n    const { levelMap, ...transportOptions } = options;\n    super(transportOptions);\n    this.target = logquillLogger;\n    this.levelMap = levelMap ?? DEFAULT_WINSTON_LEVEL_MAP;\n  }\n\n  /** winston-transport's own write hook — called by winston for every entry that reaches this transport. */\n  log(info: unknown, callback: () => void): void {\n    setImmediate(() => {\n      this.emit(\"logged\", info);\n    });\n\n    const entry = info as Record<string, unknown>;\n    const winstonLevel = typeof entry.level === \"string\" ? entry.level : \"info\";\n    const message = typeof entry.message === \"string\" ? entry.message : String(entry.message);\n\n    const meta: Record<string, unknown> = {};\n    for (const key of Object.keys(entry)) {\n      if (key !== \"level\" && key !== \"message\") {\n        meta[key] = entry[key];\n      }\n    }\n\n    callAtLevel(this.target, parseLevel(this.levelMap[winstonLevel] ?? Level.INFO), message, meta);\n    callback();\n  }\n}\n"]}

package/dist/winston.d.cts

@@ -0,0 +1,55 @@
+import Transport from 'winston-transport';
+import { c as LevelInput, b as Logger } from './logger-CRdmCDfC.cjs';
+
+/** Maps a winston level name to a LogQuill level. */
+type WinstonLevelMap = Readonly<Record<string, LevelInput>>;
+/** winston's built-in `npm` levels (its default), mapped onto the closest LogQuill level. */
+declare const DEFAULT_WINSTON_LEVEL_MAP: WinstonLevelMap;
+/** Options for {@link LogQuillWinstonTransport}, extending winston-transport's own `TransportStreamOptions` (`level`, etc.). */
+interface LogQuillWinstonTransportOptions extends Transport.TransportStreamOptions {
+    /** Overrides `DEFAULT_WINSTON_LEVEL_MAP` — useful for a winston logger configured with custom levels. An unmapped level falls back to `INFO`. */
+    levelMap?: WinstonLevelMap;
+}
+/**
+ * A `winston-transport` `Transport`, so an existing `winston.createLogger()`
+ * app can add a LogQuill `Logger` as one more destination with no call-site
+ * changes: every `.info()/.warn()/...` call already going through winston
+ * keeps working exactly as it does today, and now also flows through this
+ * transport into every LogQuill `Transport`/`Plugin` attached to the given
+ * `Logger` — handy for migrating incrementally rather than in one PR.
+ *
+ * ```ts
+ * import winston from "winston";
+ * import { Logger } from "logquill";
+ * import { LogQuillWinstonTransport } from "logquill/winston";
+ *
+ * const logquill = new Logger("app");
+ * const winstonLogger = winston.createLogger({
+ *   transports: [new LogQuillWinstonTransport(logquill)],
+ * });
+ *
+ * winstonLogger.info("still works exactly as before", { userId: 42 });
+ * ```
+ *
+ * winston's own level filtering (its logger's configured `level`, and this
+ * transport's own `level` option) runs first, same as any other winston
+ * transport; whatever reaches this transport is then mapped onto a LogQuill
+ * level via `levelMap` and re-filtered by the LogQuill `Logger`'s own
+ * `level` — the stricter of the two wins.
+ *
+ * Ships from a **separate entry point**, `import ... from "logquill/winston"`
+ * — not the main `"logquill"` import — for the same reason `LangChainAdapter`
+ * does: it has to `extends Transport`, `winston-transport`'s own class, a
+ * hard static import. Keeping it out of the main entry point means a plain
+ * `import { Logger } from "logquill"` never requires `winston-transport` to
+ * be installed. `winston-transport` is an optional peer dependency.
+ */
+declare class LogQuillWinstonTransport extends Transport {
+    private readonly target;
+    private readonly levelMap;
+    constructor(logquillLogger: Logger, options?: LogQuillWinstonTransportOptions);
+    /** winston-transport's own write hook — called by winston for every entry that reaches this transport. */
+    log(info: unknown, callback: () => void): void;
+}
+
+export { DEFAULT_WINSTON_LEVEL_MAP, LogQuillWinstonTransport, type LogQuillWinstonTransportOptions, type WinstonLevelMap };

package/dist/winston.d.ts

@@ -0,0 +1,55 @@
+import Transport from 'winston-transport';
+import { c as LevelInput, b as Logger } from './logger-CRdmCDfC.js';
+
+/** Maps a winston level name to a LogQuill level. */
+type WinstonLevelMap = Readonly<Record<string, LevelInput>>;
+/** winston's built-in `npm` levels (its default), mapped onto the closest LogQuill level. */
+declare const DEFAULT_WINSTON_LEVEL_MAP: WinstonLevelMap;
+/** Options for {@link LogQuillWinstonTransport}, extending winston-transport's own `TransportStreamOptions` (`level`, etc.). */
+interface LogQuillWinstonTransportOptions extends Transport.TransportStreamOptions {
+    /** Overrides `DEFAULT_WINSTON_LEVEL_MAP` — useful for a winston logger configured with custom levels. An unmapped level falls back to `INFO`. */
+    levelMap?: WinstonLevelMap;
+}
+/**
+ * A `winston-transport` `Transport`, so an existing `winston.createLogger()`
+ * app can add a LogQuill `Logger` as one more destination with no call-site
+ * changes: every `.info()/.warn()/...` call already going through winston
+ * keeps working exactly as it does today, and now also flows through this
+ * transport into every LogQuill `Transport`/`Plugin` attached to the given
+ * `Logger` — handy for migrating incrementally rather than in one PR.
+ *
+ * ```ts
+ * import winston from "winston";
+ * import { Logger } from "logquill";
+ * import { LogQuillWinstonTransport } from "logquill/winston";
+ *
+ * const logquill = new Logger("app");
+ * const winstonLogger = winston.createLogger({
+ *   transports: [new LogQuillWinstonTransport(logquill)],
+ * });
+ *
+ * winstonLogger.info("still works exactly as before", { userId: 42 });
+ * ```
+ *
+ * winston's own level filtering (its logger's configured `level`, and this
+ * transport's own `level` option) runs first, same as any other winston
+ * transport; whatever reaches this transport is then mapped onto a LogQuill
+ * level via `levelMap` and re-filtered by the LogQuill `Logger`'s own
+ * `level` — the stricter of the two wins.
+ *
+ * Ships from a **separate entry point**, `import ... from "logquill/winston"`
+ * — not the main `"logquill"` import — for the same reason `LangChainAdapter`
+ * does: it has to `extends Transport`, `winston-transport`'s own class, a
+ * hard static import. Keeping it out of the main entry point means a plain
+ * `import { Logger } from "logquill"` never requires `winston-transport` to
+ * be installed. `winston-transport` is an optional peer dependency.
+ */
+declare class LogQuillWinstonTransport extends Transport {
+    private readonly target;
+    private readonly levelMap;
+    constructor(logquillLogger: Logger, options?: LogQuillWinstonTransportOptions);
+    /** winston-transport's own write hook — called by winston for every entry that reaches this transport. */
+    log(info: unknown, callback: () => void): void;
+}
+
+export { DEFAULT_WINSTON_LEVEL_MAP, LogQuillWinstonTransport, type LogQuillWinstonTransportOptions, type WinstonLevelMap };

package/dist/winston.mjs

@@ -0,0 +1,101 @@
+import Transport from 'winston-transport';
+
+// src/bridges/winston-transport.ts
+
+// src/core/levels.ts
+var Level = /* @__PURE__ */ ((Level2) => {
+  Level2[Level2["TRACE"] = 5] = "TRACE";
+  Level2[Level2["DEBUG"] = 10] = "DEBUG";
+  Level2[Level2["INFO"] = 20] = "INFO";
+  Level2[Level2["WARN"] = 30] = "WARN";
+  Level2[Level2["ERROR"] = 40] = "ERROR";
+  Level2[Level2["FATAL"] = 50] = "FATAL";
+  return Level2;
+})(Level || {});
+var NAME_TO_LEVEL = {
+  TRACE: 5 /* TRACE */,
+  DEBUG: 10 /* DEBUG */,
+  INFO: 20 /* INFO */,
+  WARN: 30 /* WARN */,
+  ERROR: 40 /* ERROR */,
+  FATAL: 50 /* FATAL */
+};
+function parseLevel(level) {
+  if (typeof level === "string") {
+    const parsed = NAME_TO_LEVEL[level.toUpperCase()];
+    if (parsed === void 0) {
+      throw new Error(`Unknown log level: ${level}`);
+    }
+    return parsed;
+  }
+  if (Level[level] === void 0) {
+    throw new Error(`Unknown log level: ${String(level)}`);
+  }
+  return level;
+}
+
+// src/bridges/level-dispatch.ts
+function callAtLevel(log, level, message, meta) {
+  switch (level) {
+    case 5 /* TRACE */:
+      log.trace(message, meta);
+      return;
+    case 10 /* DEBUG */:
+      log.debug(message, meta);
+      return;
+    case 20 /* INFO */:
+      log.info(message, meta);
+      return;
+    case 30 /* WARN */:
+      log.warn(message, meta);
+      return;
+    case 40 /* ERROR */:
+      log.error(message, meta);
+      return;
+    case 50 /* FATAL */:
+      log.fatal(message, meta);
+      return;
+  }
+}
+
+// src/bridges/winston-transport.ts
+var DEFAULT_WINSTON_LEVEL_MAP = {
+  error: 40 /* ERROR */,
+  warn: 30 /* WARN */,
+  info: 20 /* INFO */,
+  http: 20 /* INFO */,
+  verbose: 10 /* DEBUG */,
+  debug: 10 /* DEBUG */,
+  silly: 5 /* TRACE */
+};
+var LogQuillWinstonTransport = class extends Transport {
+  target;
+  levelMap;
+  constructor(logquillLogger, options = {}) {
+    const { levelMap, ...transportOptions } = options;
+    super(transportOptions);
+    this.target = logquillLogger;
+    this.levelMap = levelMap ?? DEFAULT_WINSTON_LEVEL_MAP;
+  }
+  /** winston-transport's own write hook — called by winston for every entry that reaches this transport. */
+  log(info, callback) {
+    setImmediate(() => {
+      this.emit("logged", info);
+    });
+    const entry = info;
+    const winstonLevel = typeof entry.level === "string" ? entry.level : "info";
+    const message = typeof entry.message === "string" ? entry.message : String(entry.message);
+    const meta = {};
+    for (const key of Object.keys(entry)) {
+      if (key !== "level" && key !== "message") {
+        meta[key] = entry[key];
+      }
+    }
+    callAtLevel(this.target, parseLevel(this.levelMap[winstonLevel] ?? 20 /* INFO */), message, meta);
+    callback();
+  }
+};
+
+export { DEFAULT_WINSTON_LEVEL_MAP, LogQuillWinstonTransport };
+//# sourceMappingURL=winston.mjs.map
+//# sourceMappingURL=winston.mjs.map

package/dist/winston.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/levels.ts","../src/bridges/level-dispatch.ts","../src/bridges/winston-transport.ts"],"names":["Level"],"mappings":"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","file":"winston.mjs","sourcesContent":["/** Log levels, shared by name and numeric weight with the logquill-python contract. */\nexport enum Level {\n  /** Finest-grained diagnostic detail. */\n  TRACE = 5,\n  /** Diagnostic detail useful in development. */\n  DEBUG = 10,\n  /** Notable events during normal operation. */\n  INFO = 20,\n  /** Something unexpected, but not (yet) an error. */\n  WARN = 30,\n  /** An error that didn't necessarily stop the operation. */\n  ERROR = 40,\n  /** An error that precedes an unrecoverable failure. */\n  FATAL = 50,\n}\n\nconst NAME_TO_LEVEL: Readonly<Record<string, Level>> = {\n  TRACE: Level.TRACE,\n  DEBUG: Level.DEBUG,\n  INFO: Level.INFO,\n  WARN: Level.WARN,\n  ERROR: Level.ERROR,\n  FATAL: Level.FATAL,\n};\n\n/** A level given as a `Level`, a level name (any case), or its numeric weight. */\nexport type LevelInput = Level | number | string;\n\n/** The level's name, e.g. `levelName(Level.INFO) === \"INFO\"`. */\nexport function levelName(level: Level): string {\n  return Level[level];\n}\n\n/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */\nexport function parseLevel(level: LevelInput): Level {\n  if (typeof level === \"string\") {\n    const parsed = NAME_TO_LEVEL[level.toUpperCase()];\n    if (parsed === undefined) {\n      throw new Error(`Unknown log level: ${level}`);\n    }\n    return parsed;\n  }\n  if (Level[level] === undefined) {\n    throw new Error(`Unknown log level: ${String(level)}`);\n  }\n  return level;\n}\n","import { Level } from \"../core/levels.js\";\nimport type { Logger } from \"../core/logger.js\";\n\n/** Calls the `Logger` method matching `level` — shared by every bridge that maps another library's numeric/string level onto ours. */\nexport function callAtLevel(\n  log: Logger,\n  level: Level,\n  message: string,\n  meta: Record<string, unknown>,\n): void {\n  switch (level) {\n    case Level.TRACE:\n      log.trace(message, meta);\n      return;\n    case Level.DEBUG:\n      log.debug(message, meta);\n      return;\n    case Level.INFO:\n      log.info(message, meta);\n      return;\n    case Level.WARN:\n      log.warn(message, meta);\n      return;\n    case Level.ERROR:\n      log.error(message, meta);\n      return;\n    case Level.FATAL:\n      log.fatal(message, meta);\n      return;\n  }\n}\n","import Transport from \"winston-transport\";\nimport { Level, parseLevel, type LevelInput } from \"../core/levels.js\";\nimport type { Logger } from \"../core/logger.js\";\nimport { callAtLevel } from \"./level-dispatch.js\";\n\n/** Maps a winston level name to a LogQuill level. */\nexport type WinstonLevelMap = Readonly<Record<string, LevelInput>>;\n\n/** winston's built-in `npm` levels (its default), mapped onto the closest LogQuill level. */\nexport const DEFAULT_WINSTON_LEVEL_MAP: WinstonLevelMap = {\n  error: Level.ERROR,\n  warn: Level.WARN,\n  info: Level.INFO,\n  http: Level.INFO,\n  verbose: Level.DEBUG,\n  debug: Level.DEBUG,\n  silly: Level.TRACE,\n};\n\n/** Options for {@link LogQuillWinstonTransport}, extending winston-transport's own `TransportStreamOptions` (`level`, etc.). */\nexport interface LogQuillWinstonTransportOptions extends Transport.TransportStreamOptions {\n  /** Overrides `DEFAULT_WINSTON_LEVEL_MAP` — useful for a winston logger configured with custom levels. An unmapped level falls back to `INFO`. */\n  levelMap?: WinstonLevelMap;\n}\n\n/**\n * A `winston-transport` `Transport`, so an existing `winston.createLogger()`\n * app can add a LogQuill `Logger` as one more destination with no call-site\n * changes: every `.info()/.warn()/...` call already going through winston\n * keeps working exactly as it does today, and now also flows through this\n * transport into every LogQuill `Transport`/`Plugin` attached to the given\n * `Logger` — handy for migrating incrementally rather than in one PR.\n *\n * ```ts\n * import winston from \"winston\";\n * import { Logger } from \"logquill\";\n * import { LogQuillWinstonTransport } from \"logquill/winston\";\n *\n * const logquill = new Logger(\"app\");\n * const winstonLogger = winston.createLogger({\n *   transports: [new LogQuillWinstonTransport(logquill)],\n * });\n *\n * winstonLogger.info(\"still works exactly as before\", { userId: 42 });\n * ```\n *\n * winston's own level filtering (its logger's configured `level`, and this\n * transport's own `level` option) runs first, same as any other winston\n * transport; whatever reaches this transport is then mapped onto a LogQuill\n * level via `levelMap` and re-filtered by the LogQuill `Logger`'s own\n * `level` — the stricter of the two wins.\n *\n * Ships from a **separate entry point**, `import ... from \"logquill/winston\"`\n * — not the main `\"logquill\"` import — for the same reason `LangChainAdapter`\n * does: it has to `extends Transport`, `winston-transport`'s own class, a\n * hard static import. Keeping it out of the main entry point means a plain\n * `import { Logger } from \"logquill\"` never requires `winston-transport` to\n * be installed. `winston-transport` is an optional peer dependency.\n */\nexport class LogQuillWinstonTransport extends Transport {\n  private readonly target: Logger;\n  private readonly levelMap: WinstonLevelMap;\n\n  constructor(logquillLogger: Logger, options: LogQuillWinstonTransportOptions = {}) {\n    const { levelMap, ...transportOptions } = options;\n    super(transportOptions);\n    this.target = logquillLogger;\n    this.levelMap = levelMap ?? DEFAULT_WINSTON_LEVEL_MAP;\n  }\n\n  /** winston-transport's own write hook — called by winston for every entry that reaches this transport. */\n  log(info: unknown, callback: () => void): void {\n    setImmediate(() => {\n      this.emit(\"logged\", info);\n    });\n\n    const entry = info as Record<string, unknown>;\n    const winstonLevel = typeof entry.level === \"string\" ? entry.level : \"info\";\n    const message = typeof entry.message === \"string\" ? entry.message : String(entry.message);\n\n    const meta: Record<string, unknown> = {};\n    for (const key of Object.keys(entry)) {\n      if (key !== \"level\" && key !== \"message\") {\n        meta[key] = entry[key];\n      }\n    }\n\n    callAtLevel(this.target, parseLevel(this.levelMap[winstonLevel] ?? Level.INFO), message, meta);\n    callback();\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logquill",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "A logging framework with an identical mental model and JSON log shape across Node/TypeScript and Python.",
   "license": "MIT",
   "type": "module",
@@ -13,30 +13,64 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.mjs",
+      "require": "./dist/langchain.cjs"
+    },
+    "./winston": {
+      "types": "./dist/winston.d.ts",
+      "import": "./dist/winston.mjs",
+      "require": "./dist/winston.cjs"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.mjs"
     }
   },
   "files": [
     "dist"
   ],
+  "imports": {
+    "#span": {
+      "browser": "./src/core/span-browser.ts",
+      "node": "./src/core/span.ts",
+      "default": "./src/core/span.ts"
+    },
+    "#context": {
+      "browser": "./src/core/context-browser.ts",
+      "node": "./src/core/context.ts",
+      "default": "./src/core/context.ts"
+    }
+  },
   "engines": {
     "node": ">=18"
   },
   "peerDependencies": {
-    "pg": "^8.11.0",
-    "mysql2": "^3.9.0",
-    "mongodb": "^6.0.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.0.0",
     "@aws-sdk/client-dynamodb": "^3.0.0",
-    "redis": "^4.6.0 || ^5.0.0",
-    "kafkajs": "^2.2.0",
-    "amqplib": "^0.10.0",
     "@aws-sdk/client-sqs": "^3.600.0",
-    "@google-cloud/pubsub": "^4.0.0",
-    "@aws-sdk/client-cloudwatch-logs": "^3.0.0",
     "@google-cloud/logging": "^11.0.0",
+    "@google-cloud/pubsub": "^4.0.0",
+    "@langchain/core": "^1.0.0",
+    "amqplib": "^0.10.0",
     "applicationinsights": "^3.0.0",
-    "nodemailer": "^6.9.0"
+    "kafkajs": "^2.2.0",
+    "mongodb": "^6.0.0",
+    "mysql2": "^3.9.0",
+    "nodemailer": "^6.9.0",
+    "pg": "^8.11.0",
+    "redis": "^4.6.0 || ^5.0.0",
+    "winston-transport": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "winston-transport": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -104,18 +138,29 @@
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "docs": "typedoc",
+    "bench": "npm run build && node --expose-gc bench/memory.bench.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@langchain/core": "^1.2.9",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
     "@types/node": "^26.4.0",
     "@vitest/coverage-v8": "^4.1.11",
+    "esbuild": "^0.27.7",
     "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",
+    "fast-check": "^4.9.0",
+    "pino": "^10.3.1",
     "prettier": "^3.9.6",
     "tsup": "^8.5.1",
+    "typedoc": "^0.28.20",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.68.0",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "winston": "^3.19.0",
+    "winston-transport": "^4.9.0"
   }
 }