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

package/dist/examples/index.d.ts

@@ -0,0 +1,110 @@
+import { DestinationServer } from '@walkeros/server-core';
+import { Flow } from '@walkeros/core';
+
+type SchemaMode = 'auto' | 'manual';
+/**
+ * Thin cross-driver connection interface. Both drivers are adapted to this shape.
+ * Production code uses the adapters in src/drivers/*; tests inject a mock client
+ * via env.client to capture sql/args without touching a real database.
+ */
+interface SqliteClient {
+    /** Execute a SQL statement. Used for CREATE TABLE and ad-hoc commands. */
+    execute: (sql: string, args?: ReadonlyArray<unknown>) => Promise<void>;
+    /**
+     * Prepare a statement for repeated execution. Returned function binds args and runs.
+     */
+    prepare: (sql: string) => (args: ReadonlyArray<unknown>) => Promise<void>;
+    /** Close the connection. */
+    close: () => Promise<void>;
+}
+/**
+ * Factory that constructs an SqliteClient from the user's connection settings.
+ * Used by env.SqliteDriver so tests can inject a spy without mocking node_modules.
+ */
+type SqliteClientFactory = (url: string, authToken?: string) => Promise<SqliteClient>;
+interface SqliteSettings {
+    /**
+     * Connection URL. Starts with `libsql://`, `http://`, `https://`, `wss://`, `ws://`
+     * → libSQL driver. Anything else → better-sqlite3 (treated as a file path).
+     * Special value `:memory:` → in-memory (better-sqlite3).
+     */
+    url: string;
+    /** libSQL / Turso auth token. Ignored for better-sqlite3. */
+    authToken?: string;
+    /** Target table name. Defaults to `events`. */
+    table?: string;
+    /**
+     * `auto` runs `CREATE TABLE IF NOT EXISTS` with the canonical schema on init.
+     * `manual` skips CREATE TABLE. The user brings their own schema and mapping.
+     * Defaults to `auto`.
+     */
+    schema?: SchemaMode;
+    _client?: SqliteClient;
+    _runInsert?: (args: ReadonlyArray<unknown>) => Promise<void>;
+    _ownedClient?: boolean;
+}
+interface Settings {
+    sqlite: SqliteSettings;
+}
+/**
+ * Env -- optional driver override. Production leaves this undefined and the
+ * destination loads better-sqlite3 or @libsql/client dynamically. Tests
+ * provide a factory via `SqliteDriver` or a pre-built client via `client`.
+ */
+interface Env extends DestinationServer.Env {
+    SqliteDriver?: SqliteClientFactory;
+    client?: SqliteClient;
+}
+
+declare const push: Env;
+/**
+ * Simulation tracking paths. Specifies which function calls to record when
+ * running step examples through the collector.
+ */
+declare const simulation: string[];
+
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_push as push, env_simulation as simulation };
+}
+
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type SqliteStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Canonical insert into the default `events` table. `out` records the
+ * column args the prepared INSERT is bound with.
+ */
+declare const defaultInsert: SqliteStepExample;
+/**
+ * Custom table name. Verifies table overrides while using the canonical column set.
+ */
+declare const customTable: SqliteStepExample;
+/**
+ * Order event with numeric data. Confirms JSON serialization of nested values.
+ */
+declare const orderComplete: SqliteStepExample;
+/**
+ * Table override per rule -- routes this event to a dedicated table.
+ */
+declare const tableOverride: SqliteStepExample;
+/**
+ * Ignored event -- mapping.ignore: true produces no insert call.
+ */
+declare const ignoredEvent: SqliteStepExample;
+
+type step_SqliteStepExample = SqliteStepExample;
+declare const step_customTable: typeof customTable;
+declare const step_defaultInsert: typeof defaultInsert;
+declare const step_ignoredEvent: typeof ignoredEvent;
+declare const step_orderComplete: typeof orderComplete;
+declare const step_tableOverride: typeof tableOverride;
+declare namespace step {
+  export { type step_SqliteStepExample as SqliteStepExample, step_customTable as customTable, step_defaultInsert as defaultInsert, step_ignoredEvent as ignoredEvent, step_orderComplete as orderComplete, step_tableOverride as tableOverride };
+}
+
+export { env, step };

package/dist/examples/index.js

@@ -0,0 +1,214 @@
+"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);
+
+// src/examples/index.ts
+var examples_exports = {};
+__export(examples_exports, {
+  env: () => env_exports,
+  step: () => step_exports
+});
+module.exports = __toCommonJS(examples_exports);
+
+// src/examples/env.ts
+var env_exports = {};
+__export(env_exports, {
+  push: () => push,
+  simulation: () => simulation
+});
+var asyncExecute = () => Promise.resolve();
+var asyncClose = () => Promise.resolve();
+var asyncPrepare = () => () => Promise.resolve();
+var mockClient = {
+  execute: asyncExecute,
+  prepare: asyncPrepare,
+  close: asyncClose
+};
+var mockFactory = () => Promise.resolve(mockClient);
+var push = {
+  SqliteDriver: mockFactory
+};
+var simulation = ["call:client.prepare", "call:client.execute"];
+
+// src/examples/step.ts
+var step_exports = {};
+__export(step_exports, {
+  customTable: () => customTable,
+  defaultInsert: () => defaultInsert,
+  ignoredEvent: () => ignoredEvent,
+  orderComplete: () => orderComplete,
+  tableOverride: () => tableOverride
+});
+var import_core = require("@walkeros/core");
+var defaultInsert = {
+  in: (0, import_core.getEvent)("page view", {
+    timestamp: 1700000100,
+    id: "evt-1",
+    user: { session: "sess-1", id: "user-42" },
+    data: { title: "Home" },
+    source: {
+      type: "server",
+      id: "https://example.com/",
+      previous_id: "https://example.com/prev"
+    },
+    globals: { env: "prod" },
+    consent: { analytics: true }
+  }),
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000100,
+        "evt-1",
+        "page view",
+        "page",
+        "view",
+        "sess-1",
+        "user-42",
+        "https://example.com/",
+        "Home",
+        "https://example.com/prev",
+        JSON.stringify({ title: "Home" }),
+        JSON.stringify({ env: "prod" }),
+        JSON.stringify({ analytics: true })
+      ]
+    ]
+  ]
+};
+var customTable = {
+  in: (0, import_core.getEvent)("form submit", {
+    timestamp: 1700000101,
+    id: "evt-2",
+    user: { session: "sess-99", id: "" },
+    data: { type: "contact" },
+    source: {
+      type: "server",
+      id: "https://example.com/contact",
+      previous_id: ""
+    },
+    globals: {},
+    consent: {}
+  }),
+  settings: {
+    sqlite: {
+      url: ":memory:",
+      table: "siteEvents"
+    }
+  },
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000101,
+        "evt-2",
+        "form submit",
+        "form",
+        "submit",
+        "sess-99",
+        "",
+        "https://example.com/contact",
+        "",
+        "",
+        JSON.stringify({ type: "contact" }),
+        JSON.stringify({}),
+        JSON.stringify({})
+      ]
+    ]
+  ]
+};
+var orderComplete = {
+  in: (0, import_core.getEvent)("order complete", {
+    timestamp: 1700000102,
+    id: "evt-3",
+    user: { session: "", id: "" },
+    data: { id: "ORD-1", total: 99 },
+    source: { type: "server", id: "", previous_id: "" },
+    globals: {},
+    consent: {}
+  }),
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000102,
+        "evt-3",
+        "order complete",
+        "order",
+        "complete",
+        "",
+        "",
+        "",
+        "",
+        "",
+        JSON.stringify({ id: "ORD-1", total: 99 }),
+        JSON.stringify({}),
+        JSON.stringify({})
+      ]
+    ]
+  ]
+};
+var tableOverride = {
+  in: (0, import_core.getEvent)("order complete", {
+    timestamp: 1700000103,
+    id: "evt-4",
+    user: { session: "", id: "" },
+    data: { id: "ORD-2", total: 42 },
+    source: { type: "server", id: "", previous_id: "" },
+    globals: {},
+    consent: {}
+  }),
+  mapping: {
+    settings: {
+      table: "orders"
+    }
+  },
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000103,
+        "evt-4",
+        "order complete",
+        "order",
+        "complete",
+        "",
+        "",
+        "",
+        "",
+        "",
+        JSON.stringify({ id: "ORD-2", total: 42 }),
+        JSON.stringify({}),
+        JSON.stringify({})
+      ]
+    ]
+  ]
+};
+var ignoredEvent = {
+  in: (0, import_core.getEvent)("debug noise", {
+    timestamp: 1700000104,
+    id: "evt-5",
+    source: { type: "server", id: "", previous_id: "" }
+  }),
+  mapping: { ignore: true },
+  out: []
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  env,
+  step
+});

package/dist/examples/index.mjs

@@ -0,0 +1,192 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/examples/env.ts
+var env_exports = {};
+__export(env_exports, {
+  push: () => push,
+  simulation: () => simulation
+});
+var asyncExecute = () => Promise.resolve();
+var asyncClose = () => Promise.resolve();
+var asyncPrepare = () => () => Promise.resolve();
+var mockClient = {
+  execute: asyncExecute,
+  prepare: asyncPrepare,
+  close: asyncClose
+};
+var mockFactory = () => Promise.resolve(mockClient);
+var push = {
+  SqliteDriver: mockFactory
+};
+var simulation = ["call:client.prepare", "call:client.execute"];
+
+// src/examples/step.ts
+var step_exports = {};
+__export(step_exports, {
+  customTable: () => customTable,
+  defaultInsert: () => defaultInsert,
+  ignoredEvent: () => ignoredEvent,
+  orderComplete: () => orderComplete,
+  tableOverride: () => tableOverride
+});
+import { getEvent } from "@walkeros/core";
+var defaultInsert = {
+  in: getEvent("page view", {
+    timestamp: 1700000100,
+    id: "evt-1",
+    user: { session: "sess-1", id: "user-42" },
+    data: { title: "Home" },
+    source: {
+      type: "server",
+      id: "https://example.com/",
+      previous_id: "https://example.com/prev"
+    },
+    globals: { env: "prod" },
+    consent: { analytics: true }
+  }),
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000100,
+        "evt-1",
+        "page view",
+        "page",
+        "view",
+        "sess-1",
+        "user-42",
+        "https://example.com/",
+        "Home",
+        "https://example.com/prev",
+        JSON.stringify({ title: "Home" }),
+        JSON.stringify({ env: "prod" }),
+        JSON.stringify({ analytics: true })
+      ]
+    ]
+  ]
+};
+var customTable = {
+  in: getEvent("form submit", {
+    timestamp: 1700000101,
+    id: "evt-2",
+    user: { session: "sess-99", id: "" },
+    data: { type: "contact" },
+    source: {
+      type: "server",
+      id: "https://example.com/contact",
+      previous_id: ""
+    },
+    globals: {},
+    consent: {}
+  }),
+  settings: {
+    sqlite: {
+      url: ":memory:",
+      table: "siteEvents"
+    }
+  },
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000101,
+        "evt-2",
+        "form submit",
+        "form",
+        "submit",
+        "sess-99",
+        "",
+        "https://example.com/contact",
+        "",
+        "",
+        JSON.stringify({ type: "contact" }),
+        JSON.stringify({}),
+        JSON.stringify({})
+      ]
+    ]
+  ]
+};
+var orderComplete = {
+  in: getEvent("order complete", {
+    timestamp: 1700000102,
+    id: "evt-3",
+    user: { session: "", id: "" },
+    data: { id: "ORD-1", total: 99 },
+    source: { type: "server", id: "", previous_id: "" },
+    globals: {},
+    consent: {}
+  }),
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000102,
+        "evt-3",
+        "order complete",
+        "order",
+        "complete",
+        "",
+        "",
+        "",
+        "",
+        "",
+        JSON.stringify({ id: "ORD-1", total: 99 }),
+        JSON.stringify({}),
+        JSON.stringify({})
+      ]
+    ]
+  ]
+};
+var tableOverride = {
+  in: getEvent("order complete", {
+    timestamp: 1700000103,
+    id: "evt-4",
+    user: { session: "", id: "" },
+    data: { id: "ORD-2", total: 42 },
+    source: { type: "server", id: "", previous_id: "" },
+    globals: {},
+    consent: {}
+  }),
+  mapping: {
+    settings: {
+      table: "orders"
+    }
+  },
+  out: [
+    [
+      "client.runInsert",
+      [
+        1700000103,
+        "evt-4",
+        "order complete",
+        "order",
+        "complete",
+        "",
+        "",
+        "",
+        "",
+        "",
+        JSON.stringify({ id: "ORD-2", total: 42 }),
+        JSON.stringify({}),
+        JSON.stringify({})
+      ]
+    ]
+  ]
+};
+var ignoredEvent = {
+  in: getEvent("debug noise", {
+    timestamp: 1700000104,
+    id: "evt-5",
+    source: { type: "server", id: "", previous_id: "" }
+  }),
+  mapping: { ignore: true },
+  out: []
+};
+export {
+  env_exports as env,
+  step_exports as step
+};

package/dist/index.d.mts

@@ -0,0 +1,172 @@
+import { Destination as Destination$1, Mapping as Mapping$1, Flow, WalkerOS } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+
+type SchemaMode = 'auto' | 'manual';
+/**
+ * Thin cross-driver connection interface. Both drivers are adapted to this shape.
+ * Production code uses the adapters in src/drivers/*; tests inject a mock client
+ * via env.client to capture sql/args without touching a real database.
+ */
+interface SqliteClient {
+    /** Execute a SQL statement. Used for CREATE TABLE and ad-hoc commands. */
+    execute: (sql: string, args?: ReadonlyArray<unknown>) => Promise<void>;
+    /**
+     * Prepare a statement for repeated execution. Returned function binds args and runs.
+     */
+    prepare: (sql: string) => (args: ReadonlyArray<unknown>) => Promise<void>;
+    /** Close the connection. */
+    close: () => Promise<void>;
+}
+/**
+ * Factory that constructs an SqliteClient from the user's connection settings.
+ * Used by env.SqliteDriver so tests can inject a spy without mocking node_modules.
+ */
+type SqliteClientFactory = (url: string, authToken?: string) => Promise<SqliteClient>;
+interface SqliteSettings {
+    /**
+     * Connection URL. Starts with `libsql://`, `http://`, `https://`, `wss://`, `ws://`
+     * → libSQL driver. Anything else → better-sqlite3 (treated as a file path).
+     * Special value `:memory:` → in-memory (better-sqlite3).
+     */
+    url: string;
+    /** libSQL / Turso auth token. Ignored for better-sqlite3. */
+    authToken?: string;
+    /** Target table name. Defaults to `events`. */
+    table?: string;
+    /**
+     * `auto` runs `CREATE TABLE IF NOT EXISTS` with the canonical schema on init.
+     * `manual` skips CREATE TABLE. The user brings their own schema and mapping.
+     * Defaults to `auto`.
+     */
+    schema?: SchemaMode;
+    _client?: SqliteClient;
+    _runInsert?: (args: ReadonlyArray<unknown>) => Promise<void>;
+    _ownedClient?: boolean;
+}
+interface Settings {
+    sqlite: SqliteSettings;
+}
+type InitSettings = Partial<Settings>;
+interface Mapping {
+    /** Override target table for this rule. */
+    table?: string;
+}
+/**
+ * Env -- optional driver override. Production leaves this undefined and the
+ * destination loads better-sqlite3 or @libsql/client dynamically. Tests
+ * provide a factory via `SqliteDriver` or a pre-built client via `client`.
+ */
+interface Env extends DestinationServer.Env {
+    SqliteDriver?: SqliteClientFactory;
+    client?: SqliteClient;
+}
+type Types = Destination$1.Types<Settings, Mapping, Env, InitSettings>;
+interface Destination extends DestinationServer.Destination<Types> {
+    init: DestinationServer.InitFn<Types>;
+}
+type Config = {
+    settings: Settings;
+} & DestinationServer.Config<Types>;
+type InitFn = DestinationServer.InitFn<Types>;
+type PushFn = DestinationServer.PushFn<Types>;
+type PartialConfig = DestinationServer.PartialConfig<Types>;
+type PushEvents = DestinationServer.PushEvents<Mapping>;
+type Rule = Mapping$1.Rule<Mapping>;
+type Rules = Mapping$1.Rules<Rule>;
+
+type index$1_Config = Config;
+type index$1_Destination = Destination;
+type index$1_Env = Env;
+type index$1_InitFn = InitFn;
+type index$1_InitSettings = InitSettings;
+type index$1_Mapping = Mapping;
+type index$1_PartialConfig = PartialConfig;
+type index$1_PushEvents = PushEvents;
+type index$1_PushFn = PushFn;
+type index$1_Rule = Rule;
+type index$1_Rules = Rules;
+type index$1_SchemaMode = SchemaMode;
+type index$1_Settings = Settings;
+type index$1_SqliteClient = SqliteClient;
+type index$1_SqliteClientFactory = SqliteClientFactory;
+type index$1_SqliteSettings = SqliteSettings;
+type index$1_Types = Types;
+declare namespace index$1 {
+  export type { index$1_Config as Config, index$1_Destination as Destination, index$1_Env as Env, index$1_InitFn as InitFn, index$1_InitSettings as InitSettings, index$1_Mapping as Mapping, index$1_PartialConfig as PartialConfig, index$1_PushEvents as PushEvents, index$1_PushFn as PushFn, index$1_Rule as Rule, index$1_Rules as Rules, index$1_SchemaMode as SchemaMode, index$1_Settings as Settings, index$1_SqliteClient as SqliteClient, index$1_SqliteClientFactory as SqliteClientFactory, index$1_SqliteSettings as SqliteSettings, index$1_Types as Types };
+}
+
+declare const push: Env;
+/**
+ * Simulation tracking paths. Specifies which function calls to record when
+ * running step examples through the collector.
+ */
+declare const simulation: string[];
+
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_push as push, env_simulation as simulation };
+}
+
+/**
+ * Extended step example that may carry destination-level settings overrides.
+ */
+type SqliteStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+};
+/**
+ * Canonical insert into the default `events` table. `out` records the
+ * column args the prepared INSERT is bound with.
+ */
+declare const defaultInsert: SqliteStepExample;
+/**
+ * Custom table name. Verifies table overrides while using the canonical column set.
+ */
+declare const customTable: SqliteStepExample;
+/**
+ * Order event with numeric data. Confirms JSON serialization of nested values.
+ */
+declare const orderComplete: SqliteStepExample;
+/**
+ * Table override per rule -- routes this event to a dedicated table.
+ */
+declare const tableOverride: SqliteStepExample;
+/**
+ * Ignored event -- mapping.ignore: true produces no insert call.
+ */
+declare const ignoredEvent: SqliteStepExample;
+
+type step_SqliteStepExample = SqliteStepExample;
+declare const step_customTable: typeof customTable;
+declare const step_defaultInsert: typeof defaultInsert;
+declare const step_ignoredEvent: typeof ignoredEvent;
+declare const step_orderComplete: typeof orderComplete;
+declare const step_tableOverride: typeof tableOverride;
+declare namespace step {
+  export { type step_SqliteStepExample as SqliteStepExample, step_customTable as customTable, step_defaultInsert as defaultInsert, step_ignoredEvent as ignoredEvent, step_orderComplete as orderComplete, step_tableOverride as tableOverride };
+}
+
+declare const index_env: typeof env;
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_env as env, index_step as step };
+}
+
+/**
+ * Canonical columns for the auto-created events table. Order matters -- used
+ * to build both CREATE TABLE and the prepared INSERT.
+ */
+declare const CANONICAL_COLUMNS: readonly ["timestamp", "event_id", "name", "entity", "action", "session_id", "user_id", "page_url", "page_title", "referrer_url", "data", "globals", "consent"];
+declare function buildCreateTableSql(table: string): string;
+declare function buildInsertSql(table: string): string;
+/**
+ * Map a walkerOS event onto the canonical column order. JSON blobs are
+ * stringified. Missing fields become empty strings / zeros.
+ */
+declare function eventToRow(event: WalkerOS.Event): unknown[];
+
+declare function isLibsqlUrl(url: string): boolean;
+
+declare const destinationSQLite: Destination;
+
+export { CANONICAL_COLUMNS, index$1 as DestinationSQLite, buildCreateTableSql, buildInsertSql, destinationSQLite as default, destinationSQLite, eventToRow, index as examples, isLibsqlUrl };