@pikku/kysely 0.13.23 → 0.13.27

package/src/kysely-audit-service.test.ts

@@ -1,352 +0,0 @@
-import { describe, test, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-import Database from 'better-sqlite3'
-import { CamelCasePlugin, Kysely, SqliteDialect, sql } from 'kysely'
-import type { AuditEvent } from '@pikku/core/services'
-
-import { KyselyAuditService } from './kysely-audit-service.js'
-
-/**
- * The `audit` table as the docs specify it — all TEXT on every engine, so the
- * service is exercised against the same shape a project would migrate to.
- */
-const CREATE_AUDIT_TABLE = `
-  CREATE TABLE audit (
-    audit_id       TEXT NOT NULL PRIMARY KEY,
-    occurred_at    TEXT NOT NULL,
-    type           TEXT NOT NULL,
-    source         TEXT NOT NULL DEFAULT 'auto',
-    outcome        TEXT,
-    function_id    TEXT,
-    wire_type      TEXT,
-    trace_id       TEXT,
-    transaction_id TEXT,
-    query_id       TEXT,
-    user_id        TEXT,
-    org_id         TEXT,
-    pikku_user_id  TEXT,
-    tables         TEXT,
-    changed_cols   TEXT,
-    event          TEXT,
-    old            TEXT,
-    data           TEXT
-  )
-`
-
-let db: Kysely<any>
-let service: KyselyAuditService
-
-const event = (
-  overrides: Partial<AuditEvent> & Pick<AuditEvent, 'type' | 'occurredAt'>
-): AuditEvent => ({
-  source: 'explicit',
-  ...overrides,
-})
-
-beforeEach(async () => {
-  db = new Kysely<any>({
-    dialect: new SqliteDialect({ database: new Database(':memory:') }),
-  })
-  await sql.raw(CREATE_AUDIT_TABLE).execute(db)
-  service = new KyselyAuditService(db)
-})
-
-const seed = () =>
-  service.write([
-    event({
-      eventId: 'e1',
-      type: 'invoice.update',
-      occurredAt: '2026-01-01T00:00:00.000Z',
-      userIdentity: { userId: 'alice', orgId: 'org-a' },
-      metadata: { entity: 'invoice', entityId: 'inv-1' },
-    }),
-    event({
-      eventId: 'e2',
-      type: 'invoice.delete',
-      occurredAt: '2026-01-02T00:00:00.000Z',
-      userIdentity: { userId: 'bob', orgId: 'org-a' },
-    }),
-    event({
-      eventId: 'e3',
-      type: 'invoice.update',
-      occurredAt: '2026-01-03T00:00:00.000Z',
-      userIdentity: { userId: 'alice', orgId: 'org-b' },
-    }),
-  ])
-
-describe('KyselyAuditService.query', () => {
-  test('returns the trail newest first', async () => {
-    await seed()
-    const { events, nextCursor } = await service.query()
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e3', 'e2', 'e1']
-    )
-    assert.equal(nextCursor, null, 'a complete page has no next cursor')
-  })
-
-  test('round-trips the event, including parsed metadata', async () => {
-    await seed()
-    const { events } = await service.query({ types: ['invoice.update'] })
-    const first = events.find((e) => e.eventId === 'e1')!
-    assert.equal(first.type, 'invoice.update')
-    assert.equal(first.source, 'explicit')
-    assert.deepEqual(first.userIdentity, {
-      userId: 'alice',
-      orgId: 'org-a',
-      pikkuUserId: undefined,
-    })
-    assert.deepEqual(first.metadata, { entity: 'invoice', entityId: 'inv-1' })
-  })
-
-  test('keeps the wire identity of a caller who never signed in', async () => {
-    await service.write([
-      event({
-        eventId: 'e4',
-        type: 'invoice.view',
-        occurredAt: '2026-01-04T00:00:00.000Z',
-        userIdentity: { pikkuUserId: 'pk_9' },
-      }),
-    ])
-    const { events } = await service.query({ types: ['invoice.view'] })
-    assert.deepEqual(events[0]!.userIdentity, {
-      userId: undefined,
-      orgId: undefined,
-      pikkuUserId: 'pk_9',
-    })
-  })
-
-  test('filters by user', async () => {
-    await seed()
-    const { events } = await service.query({ userIds: ['alice'] })
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e3', 'e1']
-    )
-  })
-
-  test('filters by type', async () => {
-    await seed()
-    const { events } = await service.query({ types: ['invoice.delete'] })
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e2']
-    )
-  })
-
-  test('combines filters as a conjunction', async () => {
-    await seed()
-    const { events } = await service.query({
-      userIds: ['alice'],
-      types: ['invoice.update'],
-      orgId: 'org-b',
-    })
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e3']
-    )
-  })
-
-  test('an empty filter array matches nothing rather than everything', async () => {
-    await seed()
-    const byUser = await service.query({ userIds: [] })
-    assert.deepEqual(byUser.events, [])
-    const byType = await service.query({ types: [] })
-    assert.deepEqual(byType.events, [])
-  })
-
-  test('bounds by occurredAt, `from` inclusive and `to` exclusive', async () => {
-    await seed()
-    const { events } = await service.query({
-      from: '2026-01-02T00:00:00.000Z',
-      to: '2026-01-03T00:00:00.000Z',
-    })
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e2']
-    )
-  })
-
-  test('pages, reporting the next offset only while more remain', async () => {
-    await seed()
-    const first = await service.query({ limit: 2 })
-    assert.deepEqual(
-      first.events.map((e) => e.eventId),
-      ['e3', 'e2']
-    )
-    assert.equal(first.nextCursor, 2)
-
-    const second = await service.query({ limit: 2, offset: first.nextCursor! })
-    assert.deepEqual(
-      second.events.map((e) => e.eventId),
-      ['e1']
-    )
-    assert.equal(second.nextCursor, null)
-  })
-
-  // Without the audit_id tiebreak the engine may order a same-timestamp batch
-  // differently per query, which drops or repeats rows across a page boundary.
-  test('orders totally when timestamps tie', async () => {
-    const sameTime = '2026-02-01T00:00:00.000Z'
-    await service.write(
-      ['a', 'b', 'c', 'd'].map((id) =>
-        event({ eventId: id, type: 't', occurredAt: sameTime })
-      )
-    )
-    const first = await service.query({ limit: 2 })
-    const second = await service.query({ limit: 2, offset: 2 })
-    const seen = [...first.events, ...second.events].map((e) => e.eventId)
-    assert.deepEqual(seen, ['d', 'c', 'b', 'a'])
-    assert.equal(new Set(seen).size, 4, 'no row may appear on two pages')
-  })
-
-  test('caps an oversized limit', async () => {
-    await service.write(
-      Array.from({ length: 5 }, (_, i) =>
-        event({
-          eventId: `e${i}`,
-          type: 't',
-          occurredAt: `2026-03-0${i + 1}T00:00:00.000Z`,
-        })
-      )
-    )
-    const { events } = await service.query({ limit: 10_000 })
-    assert.equal(events.length, 5, 'the cap must not lose rows below it')
-  })
-
-  test('a malformed data column surfaces rather than dropping the event', async () => {
-    await sql
-      .raw(
-        `INSERT INTO audit (audit_id, occurred_at, type, source, data)
-         VALUES ('bad', '2026-04-01T00:00:00.000Z', 'legacy.write', 'auto', 'not json')`
-      )
-      .execute(db)
-    const { events } = await service.query()
-    assert.equal(events.length, 1)
-    assert.equal(events[0]!.metadata as unknown, 'not json')
-  })
-})
-
-/**
- * The two connections a project actually hands this service. `CamelCasePlugin`
- * is on almost every pikku Kysely instance, and it renames result columns on
- * the way out — `audit_id` arrives as `auditId` — so a service that only reads
- * the physical names returns a page of undefined-everything against the setup
- * most projects have.
- */
-describe('KyselyAuditService against a CamelCasePlugin connection', () => {
-  let camelDb: Kysely<any>
-  let camelService: KyselyAuditService
-
-  beforeEach(async () => {
-    camelDb = new Kysely<any>({
-      dialect: new SqliteDialect({ database: new Database(':memory:') }),
-      plugins: [new CamelCasePlugin()],
-    })
-    await sql.raw(CREATE_AUDIT_TABLE).execute(camelDb)
-    camelService = new KyselyAuditService(camelDb)
-  })
-
-  test('reads back everything it wrote', async () => {
-    await camelService.write([
-      event({
-        eventId: 'e1',
-        type: 'invoice.update',
-        occurredAt: '2026-01-01T00:00:00.000Z',
-        outcome: 'success',
-        functionId: 'cancelInvoice',
-        wireType: 'http',
-        traceId: 'trace-1',
-        userIdentity: { userId: 'alice', orgId: 'org-a' },
-        metadata: { entity: 'invoice' },
-      }),
-    ])
-    const { events } = await camelService.query()
-    assert.equal(events.length, 1)
-    assert.deepEqual(events[0], {
-      eventId: 'e1',
-      occurredAt: '2026-01-01T00:00:00.000Z',
-      type: 'invoice.update',
-      source: 'explicit',
-      outcome: 'success',
-      functionId: 'cancelInvoice',
-      wireType: 'http',
-      traceId: 'trace-1',
-      transactionId: undefined,
-      queryId: undefined,
-      userIdentity: {
-        userId: 'alice',
-        orgId: 'org-a',
-        pikkuUserId: undefined,
-      },
-      metadata: { entity: 'invoice' },
-    })
-  })
-
-  test('still filters and facets by user', async () => {
-    await camelService.write([
-      event({
-        eventId: 'e1',
-        type: 'a',
-        occurredAt: '2026-01-01T00:00:00.000Z',
-        userIdentity: { userId: 'alice' },
-      }),
-      event({
-        eventId: 'e2',
-        type: 'b',
-        occurredAt: '2026-01-02T00:00:00.000Z',
-        userIdentity: { userId: 'bob' },
-      }),
-    ])
-    const { events } = await camelService.query({ userIds: ['bob'] })
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e2']
-    )
-    const facets = await camelService.facets()
-    assert.deepEqual(facets.userIds, ['alice', 'bob'])
-  })
-})
-
-describe('KyselyAuditService.init', () => {
-  test('refuses to boot against a database that has none', async () => {
-    const fresh = new Kysely<any>({
-      dialect: new SqliteDialect({ database: new Database(':memory:') }),
-      plugins: [new CamelCasePlugin()],
-    })
-    const freshService = new KyselyAuditService(fresh)
-    await assert.rejects(freshService.init(), /pikku db generate/)
-  })
-
-  // Two boots against one database, and the second must not wipe the first.
-  test('is idempotent and keeps what is already there', async () => {
-    await service.write([
-      event({ eventId: 'e1', type: 't', occurredAt: '2026-01-01' }),
-    ])
-    await service.init()
-    await service.init()
-    const { events } = await service.query()
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e1']
-    )
-  })
-})
-
-describe('KyselyAuditService.facets', () => {
-  test('lists the distinct users and types across the whole trail', async () => {
-    await seed()
-    const facets = await service.facets()
-    assert.deepEqual(facets.userIds, ['alice', 'bob'])
-    assert.deepEqual(facets.types, ['invoice.delete', 'invoice.update'])
-  })
-
-  test('omits userless events from the user list', async () => {
-    await service.write([
-      event({ eventId: 'cron', type: 'cleanup.ran', occurredAt: '2026-05-01' }),
-    ])
-    const facets = await service.facets()
-    assert.deepEqual(facets.userIds, [])
-    assert.deepEqual(facets.types, ['cleanup.ran'])
-  })
-})

package/src/kysely-audit-service.ts

@@ -1,237 +0,0 @@
-import type { AuditService } from '@pikku/core/services'
-import type { AuditEvent, AuditEventBatch } from '@pikku/core/services'
-import type {
-  AuditFacets,
-  AuditQuery,
-  AuditQueryResult,
-} from '@pikku/core/services'
-import type { Kysely } from 'kysely'
-import { requirePikkuSchema } from './schema/index.js'
-import { auditSchema } from './schema/audit.schema.js'
-
-const jsonOrNull = (v: unknown): string | null =>
-  v != null ? JSON.stringify(v) : null
-
-const parseJson = (v: unknown): any => {
-  if (typeof v !== 'string') return v ?? undefined
-  try {
-    return JSON.parse(v)
-  } catch {
-    // A row written by something other than this service, or truncated in
-    // transit. Surfacing the raw text beats dropping the event: the row is
-    // still evidence that something happened, and swallowing it would make the
-    // trail quietly incomplete.
-    return v
-  }
-}
-
-/**
- * A column by its physical name, whatever the connection renamed it to.
- *
- * `CamelCasePlugin` is on most pikku Kysely instances and rewrites result keys
- * on the way out, so the same row arrives keyed `audit_id` or `auditId`
- * depending on a plugin this service is never told about. Reading both is
- * cheaper than demanding a particular connection — and quieter to get wrong,
- * since the mismatch does not throw, it just returns a page of undefined.
- */
-const column = (row: Record<string, any>, name: string): any => {
-  const value = row[name]
-  if (value !== undefined) return value
-  return row[name.replace(/_(\w)/g, (_, char: string) => char.toUpperCase())]
-}
-
-/** Rows are TEXT on every engine, so the shape is whatever the driver returned. */
-const rowToEvent = (row: Record<string, any>): AuditEvent => {
-  const userId = column(row, 'user_id')
-  const orgId = column(row, 'org_id')
-  const pikkuUserId = column(row, 'pikku_user_id')
-  return {
-    eventId: column(row, 'audit_id') ?? undefined,
-    occurredAt: column(row, 'occurred_at'),
-    type: row.type,
-    source: row.source ?? 'auto',
-    outcome: row.outcome ?? undefined,
-    functionId: column(row, 'function_id') ?? undefined,
-    wireType: column(row, 'wire_type') ?? undefined,
-    traceId: column(row, 'trace_id') ?? undefined,
-    transactionId: column(row, 'transaction_id') ?? undefined,
-    queryId: column(row, 'query_id') ?? undefined,
-    userIdentity:
-      userId || orgId || pikkuUserId
-        ? {
-            userId: userId ?? undefined,
-            orgId: orgId ?? undefined,
-            pikkuUserId: pikkuUserId ?? undefined,
-          }
-        : undefined,
-    metadata: parseJson(row.data),
-  }
-}
-
-/** The most a single page may return, whatever the caller asked for. */
-const MAX_LIMIT = 200
-const DEFAULT_LIMIT = 50
-
-// No global `crypto` is guaranteed across every runtime, and audit_id is the
-// PK — any collision is dropped by ON CONFLICT DO NOTHING.
-const fallbackId = (): string =>
-  `evt_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`
-
-/**
- * Durable {@link AuditService} that persists AuditEvents to an `audit` table
- * via Kysely — the companion sink to {@link createAuditedKysely}.
- *
- * The column mapping matches a platform audit-queue consumer, so a locally-run
- * project and a deployed stage write identical rows (the read side relies only
- * on `type`, `occurred_at`, `user_id`, and the `data` JSON that holds
- * `metadata`). The `audit` table is an optional per-project migration (not in
- * the generated schema), so rows are inserted untyped; all columns are TEXT on
- * every engine and ON CONFLICT DO NOTHING keeps writes idempotent on retries.
- */
-export class KyselyAuditService implements AuditService {
-  private initialized = false
-
-  constructor(private db: Kysely<any>) {}
-
-  /**
-   * Creates the `audit` table if the database has none.
-   *
-   * Optional — a project that migrates the table itself can skip it, and the
-   * declaration is written to match the documented shape either way. Calling it
-   * on a database that already has the table is a no-op, so two instances
-   * booting cold do not race each other into a half-applied schema.
-   */
-  public async init(): Promise<void> {
-    if (this.initialized) return
-    await requirePikkuSchema(this.db, auditSchema)
-    this.initialized = true
-  }
-
-  async audit(event: AuditEvent): Promise<void> {
-    await this.write([event])
-  }
-
-  async write(batch: AuditEventBatch): Promise<void> {
-    if (!batch.length) return
-    const rows = batch.map((e) => {
-      const metadata = e.metadata as
-        { tables?: unknown; changedColumns?: unknown } | undefined
-      return {
-        audit_id: e.eventId ?? e.queryId ?? fallbackId(),
-        occurred_at: e.occurredAt ?? new Date().toISOString(),
-        type: e.type ?? 'unknown',
-        source: e.source ?? 'auto',
-        outcome: e.outcome ?? null,
-        function_id: e.functionId ?? null,
-        wire_type: e.wireType ?? null,
-        trace_id: e.traceId ?? null,
-        transaction_id: e.transactionId ?? null,
-        query_id: e.queryId ?? null,
-        user_id: e.userIdentity?.userId ?? null,
-        org_id: e.userIdentity?.orgId ?? null,
-        pikku_user_id: e.userIdentity?.pikkuUserId ?? null,
-        tables: jsonOrNull(metadata?.tables),
-        changed_cols: jsonOrNull(metadata?.changedColumns),
-        event: e.eventId ?? null,
-        old: null,
-        data: jsonOrNull(e.metadata),
-      }
-    })
-    await (this.db as any)
-      .insertInto('audit')
-      .values(rows)
-      .onConflict((oc: any) => oc.doNothing())
-      .execute()
-  }
-
-  /**
-   * A page of the trail, newest first.
-   *
-   * Offset paging, matching the rest of the console. The trail is append-only
-   * and ordered by `occurred_at DESC`, so events written *while* a reader is
-   * paging shift the window and can repeat a row across pages. That is visible
-   * but harmless for browsing; anything that must not miss a row should page by
-   * a bounded `from`/`to` window instead of scrolling.
-   *
-   * Ties on `occurred_at` are broken by `audit_id` so the order is total —
-   * without it a batch flushed in one call shares a timestamp and the engine is
-   * free to order it differently per query, which drops or repeats rows at a
-   * page boundary.
-   */
-  async query(query: AuditQuery = {}): Promise<AuditQueryResult> {
-    const limit = Math.min(Math.max(query.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT)
-    const offset = Math.max(query.offset ?? 0, 0)
-
-    let builder = (this.db as any).selectFrom('audit').selectAll()
-    builder = this.applyFilters(builder, query)
-
-    const rows = await builder
-      .orderBy('occurred_at', 'desc')
-      .orderBy('audit_id', 'desc')
-      // One extra row is the cheapest honest way to know whether another page
-      // exists — a COUNT would be a second scan of the same filter.
-      .limit(limit + 1)
-      .offset(offset)
-      .execute()
-
-    const hasMore = rows.length > limit
-    return {
-      events: rows.slice(0, limit).map(rowToEvent),
-      nextCursor: hasMore ? offset + limit : null,
-    }
-  }
-
-  async facets(): Promise<AuditFacets> {
-    const [users, types] = await Promise.all([
-      (this.db as any)
-        .selectFrom('audit')
-        .select('user_id')
-        .distinct()
-        .where('user_id', 'is not', null)
-        .orderBy('user_id', 'asc')
-        .execute(),
-      (this.db as any)
-        .selectFrom('audit')
-        .select('type')
-        .distinct()
-        .orderBy('type', 'asc')
-        .execute(),
-    ])
-    return {
-      userIds: users.map((r: any) => column(r, 'user_id')),
-      types: types.map((r: any) => r.type).filter(Boolean),
-    }
-  }
-
-  /**
-   * An empty array means "match nothing" and is applied as such. Treating it as
-   * "no filter" would turn a reader's deselect-everything into a full-trail
-   * read, which is the opposite of what they asked for.
-   */
-  private applyFilters(builder: any, query: AuditQuery): any {
-    // `in ()` is a syntax error on Postgres and SQLite alike, so an empty
-    // selection is expressed as a predicate that cannot hold.
-    const matchNothing = (b: any) => b.where('audit_id', 'is', null)
-
-    if (query.userIds) {
-      builder = query.userIds.length
-        ? builder.where('user_id', 'in', query.userIds)
-        : matchNothing(builder)
-    }
-    if (query.types) {
-      builder = query.types.length
-        ? builder.where('type', 'in', query.types)
-        : matchNothing(builder)
-    }
-    if (query.orgId) {
-      builder = builder.where('org_id', '=', query.orgId)
-    }
-    if (query.from) {
-      builder = builder.where('occurred_at', '>=', query.from)
-    }
-    if (query.to) {
-      builder = builder.where('occurred_at', '<', query.to)
-    }
-    return builder
-  }
-}

package/src/kysely-channel-store.ts

@@ -1,107 +0,0 @@
-import { ChannelStore } from '@pikku/core/channel'
-import type { Channel } from '@pikku/core/channel'
-import type { Kysely } from 'kysely'
-import type { KyselyPikkuDB } from './kysely-tables.js'
-import { parseJson } from './kysely-json.js'
-import { requirePikkuSchema } from './schema/index.js'
-import { channelSchema } from './schema/channel.schema.js'
-
-export class KyselyChannelStore extends ChannelStore {
-  private initialized = false
-
-  constructor(private db: Kysely<KyselyPikkuDB>) {
-    super()
-  }
-
-  public async init(): Promise<void> {
-    if (this.initialized) return
-    await requirePikkuSchema(this.db, channelSchema)
-    this.initialized = true
-  }
-
-  public async addChannel({
-    channelId,
-    channelName,
-    openingData,
-  }: Channel): Promise<void> {
-    await this.db
-      .insertInto('channels')
-      .values({
-        channelId: channelId,
-        channelName: channelName,
-        openingData: JSON.stringify(openingData || {}),
-      })
-      .execute()
-  }
-
-  public async removeChannels(channelIds: string[]): Promise<void> {
-    if (channelIds.length === 0) {
-      return
-    }
-
-    await this.db
-      .deleteFrom('channels')
-      .where('channelId', 'in', channelIds)
-      .execute()
-  }
-
-  public async setPikkuUserId(
-    channelId: string,
-    pikkuUserId: string | null
-  ): Promise<void> {
-    await this.db
-      .updateTable('channels')
-      .set({ pikkuUserId })
-      .where('channelId', '=', channelId)
-      .execute()
-  }
-
-  public async getChannel(
-    channelId: string
-  ): Promise<Channel & { pikkuUserId?: string }> {
-    const row = await this.db
-      .selectFrom('channels')
-      .select(['channelId', 'channelName', 'openingData', 'pikkuUserId'])
-      .where('channelId', '=', channelId)
-      .executeTakeFirst()
-
-    if (!row) {
-      throw new Error(`Channel not found: ${channelId}`)
-    }
-
-    return {
-      channelId: row.channelId,
-      channelName: row.channelName,
-      openingData: parseJson(row.openingData) ?? {},
-      pikkuUserId: row.pikkuUserId ?? undefined,
-    }
-  }
-
-  public async setState(channelId: string, state: unknown): Promise<void> {
-    await this.db
-      .updateTable('channels')
-      .set({ state: JSON.stringify(state ?? null) })
-      .where('channelId', '=', channelId)
-      .execute()
-  }
-
-  public async getState(channelId: string): Promise<unknown | undefined> {
-    const row = await this.db
-      .selectFrom('channels')
-      .select(['state'])
-      .where('channelId', '=', channelId)
-      .executeTakeFirst()
-    if (!row || !row.state) return undefined
-    return parseJson(row.state) ?? undefined
-  }
-
-  public async clearState(channelId: string): Promise<void> {
-    await this.db
-      .updateTable('channels')
-      .set({ state: null })
-      .where('channelId', '=', channelId)
-      .execute()
-  }
-
-  public async close(): Promise<void> {}
-}