@walkeros/server-destination-file 3.4.0-next-1776749829492

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/helpers.ts","../src/types/index.ts"],"sourcesContent":["import { getMappingValue, isString, isObject } from '@walkeros/core';\nimport type { Destination, InitFn, PushFn, Settings } from './types';\nimport {\n  createState,\n  ensureHandle,\n  getState,\n  registerState,\n  removeState,\n  serialize,\n} from './helpers';\n\nexport * as DestinationFile from './types';\n\nconst init: InitFn = async ({ id, config, env, logger }) => {\n  const partial = (config?.settings ?? {}) as Partial<Settings>;\n  if (partial.filename === undefined || partial.filename === null) {\n    logger.throw(\n      \"file destination: 'filename' is required (string or Mapping.Value)\",\n    );\n    return false;\n  }\n  if (\n    !isString(partial.filename) &&\n    !(isObject(partial.filename) || Array.isArray(partial.filename))\n  ) {\n    logger.throw(\n      \"file destination: 'filename' must be a string or a Mapping.Value\",\n    );\n    return false;\n  }\n\n  const format = partial.format ?? 'jsonl';\n  if (\n    (format === 'tsv' || format === 'csv') &&\n    (!partial.fields || partial.fields.length === 0)\n  ) {\n    logger.throw(\n      `file destination: format '${format}' requires non-empty 'fields'`,\n    );\n    return false;\n  }\n\n  const settings: Settings = {\n    filename: partial.filename,\n    format,\n    fields: partial.fields,\n  };\n\n  const state = createState(env);\n\n  // Eager open for static filename — fail-fast on bad path.\n  if (isString(settings.filename)) {\n    try {\n      await ensureHandle(state, settings.filename);\n    } catch (err) {\n      logger.throw(\n        `file destination: failed to open '${settings.filename}': ${\n          err instanceof Error ? err.message : String(err)\n        }`,\n      );\n      return false;\n    }\n  }\n\n  registerState(id, state);\n\n  return {\n    ...config,\n    settings,\n  };\n};\n\nconst push: PushFn = async (event, { id, config, collector, logger }) => {\n  const settings = config.settings as Settings | undefined;\n  if (!settings) {\n    logger.warn('file destination: settings missing');\n    return;\n  }\n  const state = getState(id);\n  if (!state) {\n    logger.warn('file destination: state missing, init may have failed');\n    return;\n  }\n\n  let filename: string;\n  if (isString(settings.filename)) {\n    filename = settings.filename;\n  } else {\n    const resolved = await getMappingValue(event, settings.filename, {\n      collector,\n    });\n    if (!isString(resolved) || resolved.length === 0) {\n      logger.warn(\n        'file destination: dynamic filename resolved to empty or non-string, dropping event',\n      );\n      return;\n    }\n    filename = resolved;\n  }\n\n  try {\n    const handle = await ensureHandle(state, filename);\n    handle.write(serialize(event, settings.format ?? 'jsonl', settings.fields));\n  } catch (err) {\n    logger.warn(\n      `file destination: write failed for ${filename}: ${\n        err instanceof Error ? err.message : String(err)\n      }`,\n    );\n  }\n};\n\nexport const destinationFile: Destination = {\n  type: 'file',\n\n  config: {},\n\n  init,\n\n  push,\n\n  async destroy({ id }) {\n    const state = getState(id);\n    if (!state) return;\n    for (const handle of state.handles.values()) {\n      try {\n        handle.end();\n      } catch {\n        // idempotent — ignore end errors on already-closed streams\n      }\n    }\n    state.handles.clear();\n    removeState(id);\n  },\n};\n\nexport default destinationFile;\n","import {\n  createWriteStream as nodeCreateWriteStream,\n  type WriteStream,\n} from 'node:fs';\nimport { mkdir as nodeMkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\nimport { getByPath, isObject } from '@walkeros/core';\nimport type { WalkerOS } from '@walkeros/core';\nimport type { Env, FileWriteStream, Format } from './types';\n\n/**\n * State held per destination instance. Created in init(), reused by\n * push() and destroy(). Keyed by a stable instance id so tests and\n * hot-swap do not share handles across instances.\n */\nexport interface State {\n  handles: Map<string, FileWriteStream>;\n  fs: NonNullable<Env['fs']>;\n}\n\nexport function createState(env: Env | undefined): State {\n  const fsOverride = env?.fs;\n  const defaultFs: NonNullable<Env['fs']> = {\n    createWriteStream: (path: string, options: { flags: string }) =>\n      nodeCreateWriteStream(path, options),\n    mkdir: async (path: string, options: { recursive: boolean }) => {\n      await nodeMkdir(path, options);\n    },\n  };\n  return {\n    handles: new Map(),\n    fs: fsOverride ?? defaultFs,\n  };\n}\n\n/**\n * Idempotent open-or-cache. Ensures the parent directory exists and\n * appends to the file via flag 'a' (creates the file if missing).\n * Used by both init() (eager static open) and push() (lazy per-event open).\n */\nexport async function ensureHandle(\n  state: State,\n  filename: string,\n): Promise<FileWriteStream> {\n  const cached = state.handles.get(filename);\n  if (cached) return cached;\n  await state.fs.mkdir(dirname(filename) || '.', { recursive: true });\n  const handle = state.fs.createWriteStream(filename, {\n    flags: 'a',\n  }) as FileWriteStream | WriteStream;\n  state.handles.set(filename, handle);\n  return handle;\n}\n\n/**\n * Format an event into a single output line (with trailing newline).\n * One implementation, used by push() for all three formats.\n */\nexport function serialize(\n  event: WalkerOS.Event,\n  format: Format,\n  fields: string[] | undefined,\n): string {\n  if (format === 'jsonl') {\n    return JSON.stringify(event) + '\\n';\n  }\n  if (!fields || fields.length === 0) {\n    throw new Error(\n      `file destination: format '${format}' requires non-empty 'fields' setting`,\n    );\n  }\n  const cells = fields.map((path) =>\n    formatCell(getByPath(event as unknown as WalkerOS.Properties, path)),\n  );\n  if (format === 'tsv') {\n    return cells.join('\\t') + '\\n';\n  }\n  // csv\n  return cells.map(csvEscape).join(',') + '\\n';\n}\n\nfunction formatCell(value: unknown): string {\n  if (value === null || value === undefined) return '';\n  if (isObject(value) || Array.isArray(value)) return JSON.stringify(value);\n  if (typeof value === 'string') return value;\n  if (typeof value === 'number' || typeof value === 'boolean')\n    return String(value);\n  return JSON.stringify(value);\n}\n\n/**\n * RFC 4180 CSV escaping: wrap in quotes if the value contains\n * comma, quote, CR, or LF; double up internal quotes.\n */\nfunction csvEscape(value: string): string {\n  if (/[\",\\r\\n]/.test(value)) {\n    return `\"${value.replace(/\"/g, '\"\"')}\"`;\n  }\n  return value;\n}\n\n/**\n * Module-level state map keyed by destination instance id. Plan Task 5\n * documents this as the fallback to config-attached symbols. Each\n * destination instance has a unique id; destroy() removes its entry.\n */\nconst states = new Map<string, State>();\n\nexport function registerState(id: string, state: State): void {\n  states.set(id, state);\n}\n\nexport function getState(id: string): State | undefined {\n  return states.get(id);\n}\n\nexport function removeState(id: string): void {\n  states.delete(id);\n}\n","import type {\n  Destination as CoreDestination,\n  Mapping as CoreMapping,\n} from '@walkeros/core';\nimport type { DestinationServer } from '@walkeros/server-core';\nimport type { WriteStream } from 'node:fs';\n\nexport type Format = 'jsonl' | 'tsv' | 'csv';\n\nexport interface Settings {\n  /**\n   * Output filename. Either a static string or a Mapping.Value resolved\n   * per event (e.g. tenant sharding via `key`, daily rotation via `$code:` fn).\n   * Static filenames are validated and opened at flow startup;\n   * dynamic ones at first matching event.\n   */\n  filename: string | CoreMapping.Value;\n\n  /** Serialisation format. Defaults to 'jsonl'. */\n  format?: Format;\n\n  /**\n   * Event paths used as columns for tsv/csv formats. Order preserved.\n   * Object values are JSON-stringified into a single cell.\n   * Required when format is 'tsv' or 'csv'.\n   */\n  fields?: string[];\n}\n\nexport type InitSettings = Partial<Settings>;\n\nexport interface Mapping {}\n\n/**\n * Minimal write-stream interface used by the destination. Matches the\n * subset of node:fs WriteStream needed for append-only writes. Tests\n * inject a fake implementation via env.fs.\n */\nexport interface FileWriteStream {\n  write: (chunk: string) => boolean;\n  end: () => void;\n}\n\nexport interface Env extends DestinationServer.Env {\n  /**\n   * Override the file system primitives. Tests inject a fake here so\n   * disk writes are captured in memory.\n   */\n  fs?: {\n    createWriteStream: (\n      path: string,\n      options: { flags: string },\n    ) => FileWriteStream | WriteStream;\n    mkdir: (path: string, options: { recursive: boolean }) => Promise<void>;\n  };\n}\n\nexport type Types = CoreDestination.Types<Settings, Mapping, Env, InitSettings>;\n\nexport interface Destination extends DestinationServer.Destination<Types> {\n  init: DestinationServer.InitFn<Types>;\n}\n\nexport type Config = {\n  settings: Settings;\n} & DestinationServer.Config<Types>;\n\nexport type PartialConfig = DestinationServer.PartialConfig<Types>;\nexport type InitFn = DestinationServer.InitFn<Types>;\nexport type PushFn = DestinationServer.PushFn<Types>;\n"],"mappings":"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","names":["isObject","isObject"]}

package/dist/walkerOS.json

@@ -0,0 +1,508 @@
+{
+  "$meta": {
+    "package": "@walkeros/server-destination-file",
+    "version": "3.4.0-next-1776749829492",
+    "type": "destination",
+    "platform": [
+      "server"
+    ],
+    "docs": "https://www.walkeros.io/docs/destinations/server/file",
+    "source": "https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/file/src"
+  },
+  "schemas": {
+    "mapping": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false,
+      "description": "No per-rule overrides for the file destination."
+    },
+    "settings": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "properties": {
+        "filename": {
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "Static output filename."
+            },
+            {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {},
+              "description": "Mapping.Value resolved per event (e.g. { key: \"data.tenant\" } or { fn: \"$code:...\" })."
+            }
+          ],
+          "description": "Output filename. Static string or Mapping.Value (e.g. { fn: \"$code:...\" } for daily rotation, { key: \"data.tenant\" } for sharding)."
+        },
+        "format": {
+          "description": "Serialisation format. Defaults to jsonl.",
+          "type": "string",
+          "enum": [
+            "jsonl",
+            "tsv",
+            "csv"
+          ]
+        },
+        "fields": {
+          "description": "Event paths used as columns for tsv/csv formats. Object values are JSON-stringified. Required when format is tsv or csv.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "filename"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "examples": {
+    "env": {
+      "init": {
+        "_spy": {
+          "captured": {},
+          "mkdirCalls": []
+        },
+        "fs": {
+          "createWriteStream": {
+            "$code": "t=>{const s=e.captured.get(t),a=null!=s?s:{filename:t,lines:[],ended:!1};s||e.captured.set(t,a);return{write:e=>(a.lines.push(e),!0),end(){a.ended=!0}}}"
+          },
+          "mkdir": {
+            "$code": "async t=>{e.mkdirCalls.push(t)}"
+          }
+        }
+      },
+      "push": {
+        "_spy": {
+          "captured": {},
+          "mkdirCalls": []
+        },
+        "fs": {
+          "createWriteStream": {
+            "$code": "t=>{const s=e.captured.get(t),a=null!=s?s:{filename:t,lines:[],ended:!1};s||e.captured.set(t,a);return{write:e=>(a.lines.push(e),!0),end(){a.ended=!0}}}"
+          },
+          "mkdir": {
+            "$code": "async t=>{e.mkdirCalls.push(t)}"
+          }
+        }
+      }
+    },
+    "step": {
+      "csvObjectCell": {
+        "in": {
+          "name": "page view",
+          "data": {
+            "title": "Hello, \"World\"",
+            "count": 3
+          },
+          "context": {
+            "dev": [
+              "test",
+              1
+            ]
+          },
+          "globals": {
+            "pagegroup": "docs"
+          },
+          "custom": {
+            "completely": "random"
+          },
+          "user": {
+            "id": "us3r",
+            "device": "c00k13",
+            "session": "s3ss10n"
+          },
+          "nested": [
+            {
+              "entity": "child",
+              "data": {
+                "is": "subordinated"
+              },
+              "nested": [],
+              "context": {
+                "element": [
+                  "child",
+                  0
+                ]
+              }
+            }
+          ],
+          "consent": {
+            "functional": true
+          },
+          "id": "1700000000000-gr0up-1",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000000000,
+          "timing": 3.14,
+          "group": "gr0up",
+          "count": 1,
+          "version": {
+            "source": "3.4.0-next-1776749829492",
+            "tagging": 1
+          },
+          "source": {
+            "type": "web",
+            "id": "https://localhost:80",
+            "previous_id": "http://remotehost:9001"
+          }
+        },
+        "settings": {
+          "filename": "events.csv",
+          "format": "csv",
+          "fields": [
+            "timestamp",
+            "name",
+            "data"
+          ]
+        },
+        "out": [
+          [
+            "fs.writeFile",
+            "events.csv",
+            "1700000000000,page view,\"{\"\"title\"\":\"\"Hello, \\\"\"World\\\"\"\"\",\"\"count\"\":3}\"\n"
+          ]
+        ]
+      },
+      "jsonlDailyRotation": {
+        "in": {
+          "name": "order complete",
+          "data": {
+            "id": "ORD-1"
+          },
+          "context": {
+            "shopping": [
+              "complete",
+              0
+            ]
+          },
+          "globals": {
+            "pagegroup": "shop"
+          },
+          "custom": {
+            "completely": "random"
+          },
+          "user": {
+            "id": "us3r",
+            "device": "c00k13",
+            "session": "s3ss10n"
+          },
+          "nested": [
+            {
+              "entity": "product",
+              "data": {
+                "id": "ers",
+                "name": "Everyday Ruck Snack",
+                "color": "black",
+                "size": "l",
+                "price": 420
+              },
+              "context": {
+                "shopping": [
+                  "complete",
+                  0
+                ]
+              },
+              "nested": []
+            },
+            {
+              "entity": "product",
+              "data": {
+                "id": "cc",
+                "name": "Cool Cap",
+                "size": "one size",
+                "price": 42
+              },
+              "context": {
+                "shopping": [
+                  "complete",
+                  0
+                ]
+              },
+              "nested": []
+            },
+            {
+              "entity": "gift",
+              "data": {
+                "name": "Surprise"
+              },
+              "context": {
+                "shopping": [
+                  "complete",
+                  0
+                ]
+              },
+              "nested": []
+            }
+          ],
+          "consent": {
+            "functional": true
+          },
+          "id": "1776256496000-gr0up-1",
+          "trigger": "load",
+          "entity": "order",
+          "action": "complete",
+          "timestamp": 1776256496000,
+          "timing": 3.14,
+          "group": "gr0up",
+          "count": 1,
+          "version": {
+            "source": "3.4.0-next-1776749829492",
+            "tagging": 1
+          },
+          "source": {
+            "type": "web",
+            "id": "https://localhost:80",
+            "previous_id": "http://remotehost:9001"
+          }
+        },
+        "settings": {
+          "filename": {
+            "fn": {
+              "$code": "e=>{var t;const s=null!=(t=e.timestamp)?t:0;return`events-${new Date(s).toISOString().slice(0,10)}.jsonl`}"
+            }
+          },
+          "format": "jsonl"
+        },
+        "out": [
+          [
+            "fs.writeFile",
+            "events-2026-04-15.jsonl",
+            "jsonl:event"
+          ]
+        ]
+      },
+      "jsonlDefault": {
+        "in": {
+          "name": "page view",
+          "data": {
+            "domain": "www.example.com",
+            "title": "walkerOS documentation",
+            "referrer": "https://www.walkeros.io/",
+            "search": "?foo=bar",
+            "hash": "#hash",
+            "id": "/docs/"
+          },
+          "context": {
+            "dev": [
+              "test",
+              1
+            ]
+          },
+          "globals": {
+            "pagegroup": "docs"
+          },
+          "custom": {
+            "completely": "random"
+          },
+          "user": {
+            "id": "us3r",
+            "device": "c00k13",
+            "session": "s3ss10n"
+          },
+          "nested": [
+            {
+              "entity": "child",
+              "data": {
+                "is": "subordinated"
+              },
+              "nested": [],
+              "context": {
+                "element": [
+                  "child",
+                  0
+                ]
+              }
+            }
+          ],
+          "consent": {
+            "functional": true
+          },
+          "id": "1700000000000-gr0up-1",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000000000,
+          "timing": 3.14,
+          "group": "gr0up",
+          "count": 1,
+          "version": {
+            "source": "3.4.0-next-1776749829492",
+            "tagging": 1
+          },
+          "source": {
+            "type": "web",
+            "id": "https://localhost:80",
+            "previous_id": "http://remotehost:9001"
+          }
+        },
+        "settings": {
+          "filename": "events.jsonl"
+        },
+        "out": [
+          [
+            "fs.writeFile",
+            "events.jsonl",
+            "jsonl:event"
+          ]
+        ]
+      },
+      "jsonlTenantShardKey": {
+        "in": {
+          "name": "custom event",
+          "data": {
+            "tenant": "acme"
+          },
+          "context": {
+            "dev": [
+              "test",
+              1
+            ]
+          },
+          "globals": {
+            "lang": "elb"
+          },
+          "custom": {
+            "completely": "random"
+          },
+          "user": {
+            "id": "us3r",
+            "device": "c00k13",
+            "session": "s3ss10n"
+          },
+          "nested": [
+            {
+              "entity": "child",
+              "data": {
+                "is": "subordinated"
+              },
+              "nested": [],
+              "context": {
+                "element": [
+                  "child",
+                  0
+                ]
+              }
+            }
+          ],
+          "consent": {
+            "functional": true
+          },
+          "id": "1700000000000-gr0up-1",
+          "trigger": "test",
+          "entity": "custom",
+          "action": "event",
+          "timestamp": 1700000000000,
+          "timing": 3.14,
+          "group": "gr0up",
+          "count": 1,
+          "version": {
+            "source": "3.4.0-next-1776749829492",
+            "tagging": 1
+          },
+          "source": {
+            "type": "web",
+            "id": "https://localhost:80",
+            "previous_id": "http://remotehost:9001"
+          }
+        },
+        "settings": {
+          "filename": {
+            "key": "data.tenant"
+          },
+          "format": "jsonl"
+        },
+        "out": [
+          [
+            "fs.writeFile",
+            "acme",
+            "jsonl:event"
+          ]
+        ]
+      },
+      "tsvBaerschLog": {
+        "in": {
+          "name": "page view",
+          "data": {
+            "title": "Docs"
+          },
+          "context": {
+            "dev": [
+              "test",
+              1
+            ]
+          },
+          "globals": {
+            "pagegroup": "docs"
+          },
+          "custom": {
+            "completely": "random"
+          },
+          "user": {
+            "session": "sess-1"
+          },
+          "nested": [
+            {
+              "entity": "child",
+              "data": {
+                "is": "subordinated"
+              },
+              "nested": [],
+              "context": {
+                "element": [
+                  "child",
+                  0
+                ]
+              }
+            }
+          ],
+          "consent": {
+            "functional": true
+          },
+          "id": "1700000000000-gr0up-1",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000000000,
+          "timing": 3.14,
+          "group": "gr0up",
+          "count": 1,
+          "version": {
+            "source": "3.4.0-next-1776749829492",
+            "tagging": 1
+          },
+          "source": {
+            "id": "https://example.com/docs",
+            "type": "server",
+            "previous_id": "https://example.com/"
+          }
+        },
+        "settings": {
+          "filename": "storage/mblog.txt",
+          "format": "tsv",
+          "fields": [
+            "timestamp",
+            "user.session",
+            "name",
+            "source.id",
+            "data.title",
+            "source.previous_id"
+          ]
+        },
+        "out": [
+          [
+            "fs.writeFile",
+            "storage/mblog.txt",
+            "1700000000000\tsess-1\tpage view\thttps://example.com/docs\tDocs\thttps://example.com/\n"
+          ]
+        ]
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@walkeros/server-destination-file",
+  "description": "Local file sink for walkerOS server flows (JSONL, TSV, CSV)",
+  "version": "3.4.0-next-1776749829492",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./dev": {
+      "types": "./dist/dev.d.ts",
+      "import": "./dist/dev.mjs",
+      "require": "./dist/dev.js"
+    },
+    "./walkerOS.json": "./dist/walkerOS.json",
+    "./examples": {
+      "types": "./dist/examples/index.d.ts",
+      "import": "./dist/examples/index.mjs",
+      "require": "./dist/examples/index.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "build": "tsup --silent",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "dev": "jest --watchAll --colors",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"**/*.ts*\"",
+    "test": "jest",
+    "update": "npx npm-check-updates -u && npm update"
+  },
+  "dependencies": {
+    "@walkeros/core": "3.4.0-next-1776749829492",
+    "@walkeros/server-core": "3.4.0-next-1776749829492"
+  },
+  "devDependencies": {
+    "@walkeros/collector": "3.4.0-next-1776749829492"
+  },
+  "repository": {
+    "url": "git+https://github.com/elbwalker/walkerOS.git",
+    "directory": "packages/server/destinations/file"
+  },
+  "author": "elbwalker <hello@elbwalker.com>",
+  "homepage": "https://github.com/elbwalker/walkerOS#readme",
+  "bugs": {
+    "url": "https://github.com/elbwalker/walkerOS/issues"
+  },
+  "walkerOS": {
+    "type": "destination",
+    "platform": [
+      "server"
+    ],
+    "docs": "https://www.walkeros.io/docs/destinations/server/file"
+  },
+  "keywords": [
+    "walkerOS",
+    "walkerOS-destination",
+    "destination",
+    "server",
+    "file",
+    "jsonl",
+    "tsv",
+    "csv",
+    "log"
+  ],
+  "funding": [
+    {
+      "type": "GitHub Sponsors",
+      "url": "https://github.com/sponsors/elbwalker"
+    }
+  ]
+}