@owlmeans/planning-postgres 0.1.18-rc.0

package/tests/fold.spec.ts

@@ -0,0 +1,213 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { uuid } from '@owlmeans/basic-ids'
+import {
+  CommitFailed, CommitState, isPending, TITLE_MAX, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type { PlanningFacade, PlanningPlugin, Transition } from '@owlmeans/planning'
+import { advisoryKey } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import { createBook, createBranch, LIBRARY, planningConformancePlugin } from '@owlmeans/server-planning/conformance'
+import { Client } from 'pg'
+
+import { LOST_ALLOCATION, RES_PLANNING_CARD } from '../src/index.js'
+import type { Booted } from './context.js'
+import { gate, makeSuite } from './context.js'
+
+/** A lending library's books, folded under the conditions a two-round-trip append creates. */
+const suite = makeSuite('fold')
+const it = gate.skip ? test.skip : test
+
+const LIMITS = { gapGraceMs: 300, healAfterMs: 50, lockTimeoutMs: 300 }
+
+describe('@owlmeans/planning-postgres — the fold', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  let booted: Booted
+  const hooked: Array<[string, TransitionAction]> = []
+
+  /** Catalogues a new book from its own `after` hook — a write to the very card that just committed. */
+  const catalogue: PlanningPlugin = {
+    name: 'catalogue',
+    after: async (event, ctx) => {
+      hooked.push([event.transition, event.action])
+      if (event.action === TransitionAction.Create && event.type === LIBRARY.book) {
+        await ctx.facade.execute({
+          card: event.card, action: TransitionAction.Update, changes: { description: 'Catalogued' }, key: `catalogue:${event.card}`,
+        })
+      }
+    },
+  }
+
+  beforeAll(async () => {
+    booted = await suite.boot({ limits: LIMITS, plugins: [planningConformancePlugin, catalogue] })
+  })
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  const start = async (): Promise<{ org: string, planning: PlanningFacade, book: string }> => {
+    const org = `library-${uuid()}`
+    const planning = booted.facade(org)
+    const branch = await createBranch(planning)
+    const book = await createBook(planning, branch.id!)
+    return { org, planning, book: book.id! }
+  }
+
+  const row = (org: string, card: string, seq: number, patch: Partial<Transition> = {}): Transition => ({
+    entityId: org, card, kind: WorkcardKind.Card, type: LIBRARY.book, seq, action: TransitionAction.Update,
+    changes: {}, actor: {}, at: new Date().toISOString(), commit: { state: CommitState.Pending }, ...patch,
+  })
+
+  const stateOf = async (id: string): Promise<CommitState | undefined> =>
+    (await booted.store.transitions.get(id))?.commit.state
+
+  it('an after hook runs once per commit, after it, and may write to the card it saw commit', async () => {
+    const { planning, book } = await start()
+
+    expect((await planning.cards.get(book)).description).toBe('Catalogued')
+    const created = hooked.filter(([, action]) => action === TransitionAction.Create)
+    expect(new Set(created.map(([transition]) => transition)).size).toBe(created.length)
+    const updates = (await planning.transitions.list({ card: book })).items.filter(entry => entry.action === TransitionAction.Update)
+    expect(updates).toHaveLength(1)
+    expect(hooked.filter(([transition]) => transition === updates[0].id)).toHaveLength(1)
+  })
+
+  it('a young gap waits for its appender, whose own fold then commits both', async () => {
+    const { org, planning, book } = await start()
+    const at = (await booted.store.transitions.nextSeq(book, null))
+    const next = await booted.store.transitions.nextSeq(book, null)
+    const third = await booted.store.transitions.append(row(org, book, next, { changes: { title: 'Third' } }))
+    await booted.store.cards.project(book)
+
+    expect(await stateOf(third.id!)).toBe(CommitState.Pending)
+    expect((await planning.cards.get(book)).seq).toBe(2)
+
+    const second = await booted.store.transitions.append(row(org, book, at, { changes: { title: 'Second' } }))
+    await booted.store.cards.project(book)
+
+    expect([await stateOf(second.id!), await stateOf(third.id!)]).toEqual([CommitState.Committed, CommitState.Committed])
+    const card = await planning.cards.get(book)
+    expect([card.title, card.seq, card.head]).toEqual(['Third', 4, 4])
+  })
+
+  it('an allocation lost past the grace becomes a failed placeholder the fold steps over', async () => {
+    const { org, planning, book } = await start()
+    await booted.store.transitions.nextSeq(book, null)
+    const next = await booted.store.transitions.nextSeq(book, null)
+    const late = await booted.store.transitions.append(row(org, book, next, {
+      changes: { title: 'After the hole' }, at: new Date(Date.now() - 3_600_000).toISOString(),
+    }))
+    await booted.store.cards.project(book)
+
+    expect(await stateOf(late.id!)).toBe(CommitState.Committed)
+    const hole = (await planning.transitions.list({ card: book, size: 0 })).items.find(entry => entry.seq === next - 1)!
+    expect([hole.commit.state, hole.cause, hole.commit.error]).toEqual([CommitState.Failed, LOST_ALLOCATION, LOST_ALLOCATION])
+    expect((await planning.cards.get(book)).title).toBe('After the hole')
+  })
+
+  it('an allocation lost with no row at all is released by the next fold', async () => {
+    const { planning, book } = await start()
+    await booted.store.transitions.nextSeq(book, null)
+    expect(isPending(await planning.cards.get(book))).toBe(true)
+
+    await new Promise(resolve => setTimeout(resolve, LIMITS.gapGraceMs + 50))
+    await booted.store.fold(book)
+
+    const card = await planning.cards.get(book)
+    expect(isPending(card)).toBe(false)
+    await planning.execute({ card: book, action: TransitionAction.Update, changes: { title: 'Moving on' } }, { wait: true })
+    expect((await planning.cards.get(book)).title).toBe('Moving on')
+  })
+
+  it('a failed row at the cursor is folded past without failing the next one', async () => {
+    const { org, planning, book } = await start()
+    const failed = await booted.store.transitions.append(row(org, book, await booted.store.transitions.nextSeq(book, null)))
+    await booted.store.transitions.commit(failed.id!, { state: CommitState.Failed, at: new Date().toISOString(), error: 'refused elsewhere' })
+    const after = await booted.store.transitions.append(row(org, book, await booted.store.transitions.nextSeq(book, null), {
+      changes: { title: 'Not out of order' },
+    }))
+    await booted.store.cards.project(book)
+
+    expect(await stateOf(after.id!)).toBe(CommitState.Committed)
+    expect((await planning.cards.get(book)).title).toBe('Not out of order')
+  })
+
+  it('a write the database refuses fails that transition alone, and the fold goes on', async () => {
+    const { org, planning, book } = await start()
+    const before = await planning.cards.get(book)
+    const oversized = await booted.store.transitions.append(row(org, book, await booted.store.transitions.nextSeq(book, null), {
+      changes: { title: 'x'.repeat(TITLE_MAX + 10) },
+    }))
+    await booted.store.cards.project(book)
+
+    const status = await booted.store.commits.status(oversized.id!)
+    expect(status.state).toBe(CommitState.Failed)
+    const card = await planning.cards.get(book)
+    expect([card.title, card.seq]).toEqual([before.title, before.seq + 1])
+
+    await planning.execute({ card: book, action: TransitionAction.Update, changes: { title: 'Fits' } }, { wait: true })
+    expect((await planning.cards.get(book)).title).toBe('Fits')
+  })
+
+  it('a transaction a statement broke is retried, then its pending transitions fail for their waiters', async () => {
+    const { planning, book } = await start()
+    const schema = `"${suite.schema}"`
+    await booted.pg.query(
+      `CREATE OR REPLACE FUNCTION ${schema}.refuse_commit() RETURNS trigger AS $$ BEGIN`
+      + ` IF NEW."card" = '${book}' AND NEW."commit"->>'state' = 'committed' THEN RAISE EXCEPTION 'refused by the shelf'; END IF;`
+      + ` RETURN NEW; END $$ LANGUAGE plpgsql`
+    )
+    await booted.pg.query(
+      `CREATE TRIGGER refuse_commit BEFORE UPDATE ON ${schema}."planning_transition" FOR EACH ROW EXECUTE FUNCTION ${schema}.refuse_commit()`
+    )
+    try {
+      const receipt = await planning.execute({ card: book, action: TransitionAction.Update, changes: { title: 'Never' } })
+      const refusal = await receipt.committed({ timeout: 5_000 }).catch(error => error)
+      expect(refusal).toBeInstanceOf(CommitFailed)
+      expect(refusal.message).toContain('refused by the shelf')
+      expect((await planning.cards.get(book)).title).not.toBe('Never')
+    } finally {
+      await booted.pg.query(`DROP TRIGGER refuse_commit ON ${schema}."planning_transition"`)
+    }
+
+    await planning.execute({ card: book, action: TransitionAction.Update, changes: { title: 'Afterwards' } }, { wait: true })
+    expect((await planning.cards.get(book)).title).toBe('Afterwards')
+  })
+
+  it('a fold that cannot take the card\'s lock yields, and a waiter heals it once the lock is free', async () => {
+    const { planning, book } = await start()
+    const table = booted.context.resource<PostgresResource<never>>(RES_PLANNING_CARD).table.qualified
+    const [first, second] = advisoryKey(`planning:${table}:${book}`)
+    const holder = new Client({ connectionString: gate.env.POSTGRES_URL as string })
+    await holder.connect()
+    try {
+      await holder.query('BEGIN')
+      await holder.query('SELECT pg_advisory_xact_lock($1, $2)', [first, second])
+
+      const receipt = await planning.execute({ card: book, action: TransitionAction.Update, changes: { title: 'Held back' } })
+      expect(receipt.transition.commit.state).toBe(CommitState.Pending)
+      const waiting = planning.commits.wait(receipt.transition.id!, { timeout: 8_000 })
+
+      await new Promise(resolve => setTimeout(resolve, 100))
+      await holder.query('ROLLBACK')
+      expect((await waiting)?.title).toBe('Held back')
+    } finally {
+      await holder.end().catch(() => undefined)
+    }
+  }, 15_000)
+
+  it('recover folds what no process is folding', async () => {
+    const { org, book } = await start()
+    const stale = await booted.store.transitions.append(row(org, book, await booted.store.transitions.nextSeq(book, null), {
+      changes: { title: 'Recovered' }, at: new Date(Date.now() - 120_000).toISOString(),
+    }))
+
+    expect(await booted.store.recover({ olderThanMs: 60_000 })).toBeGreaterThanOrEqual(1)
+    expect(await stateOf(stale.id!)).toBe(CommitState.Committed)
+  })
+})

package/tests/schema.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, spyOn, test } from 'bun:test'
+import { getDeclaration, resetDeclarations, schemaToTableSpec } from '@owlmeans/postgres-resource'
+
+import {
+  makePlanningCardPostgres, makePlanningLinkPostgres, makePlanningSchemaPostgres, makePlanningTransitionPostgres,
+  PlanningCardTableSchema, PlanningLinkTableSchema, PlanningSchemaTableSchema, PlanningTransitionTableSchema,
+  RES_PLANNING_CARD, RES_PLANNING_LINK, RES_PLANNING_SCHEMA, RES_PLANNING_TRANSITION,
+} from '../src/index.js'
+
+/**
+ * No database: `schemaToTableSpec` is the compiler `init()` runs, so what a table becomes is pinned
+ * here — above all that no timestamp becomes `timestamptz`, which would marshal through `Date` and
+ * break the ISO-string order the store relies on.
+ */
+describe('@owlmeans/planning-postgres — table shapes', () => {
+  test('the card table: text timestamps, integer counters, text body, a private headAt', () => {
+    const spec = schemaToTableSpec(RES_PLANNING_CARD, PlanningCardTableSchema, 'app', 'planning_card', true)
+    const typeOf = (property: string) => [spec.byProperty[property].sqlType, spec.byProperty[property].jsonType]
+
+    for (const timestamp of ['createdAt', 'updatedAt', 'closedAt', 'headAt']) {
+      expect([timestamp, ...typeOf(timestamp)]).toEqual([timestamp, 'text', 'string'])
+    }
+    for (const counter of ['seq', 'head', 'revision', 'bodyChars']) {
+      expect([counter, typeOf(counter)[0]]).toEqual([counter, 'integer'])
+    }
+    expect(typeOf('body')[0]).toBe('text')
+    expect(typeOf('order')[0]).toBe('double precision')
+    expect([spec.byProperty.parents.array, spec.byProperty.labels.array]).toEqual([true, true])
+    expect([spec.byProperty.fields.jsonb, spec.byProperty.flows.jsonb]).toEqual([true, true])
+    expect(spec.byProperty.createdAt.notNull).toBe(true)
+    expect(spec.byProperty.headAt.notNull).toBe(false)
+  })
+
+  test('the log, the links and the schema records keep text timestamps too', () => {
+    const log = schemaToTableSpec(RES_PLANNING_TRANSITION, PlanningTransitionTableSchema, 'app', 'planning_transition', true)
+    const links = schemaToTableSpec(RES_PLANNING_LINK, PlanningLinkTableSchema, 'app', 'planning_link', true)
+    const schemas = schemaToTableSpec(RES_PLANNING_SCHEMA, PlanningSchemaTableSchema, 'app', 'planning_schema', true)
+
+    expect([log.byProperty.at.sqlType, log.byProperty.seq.sqlType, log.byProperty.commit.jsonb]).toEqual(['text', 'integer', true])
+    expect(links.byProperty.createdAt.sqlType).toBe('text')
+    expect([schemas.byProperty.version.sqlType, schemas.byProperty.rev.sqlType, schemas.byProperty.project.sqlType]).toEqual(['integer', 'integer', 'text'])
+    // The private revision row is a legal kind.
+    expect(schemas.checks.find(check => check.name?.endsWith('_kind_enum'))?.expression).toContain(`'head'`)
+  })
+
+  test('each maker declares its indexes once, however often it runs', () => {
+    for (const alias of [RES_PLANNING_CARD, RES_PLANNING_TRANSITION, RES_PLANNING_LINK, RES_PLANNING_SCHEMA]) {
+      resetDeclarations(alias)
+    }
+    const warn = spyOn(console, 'warn')
+    try {
+      for (let run = 0; run < 2; run++) {
+        makePlanningCardPostgres()
+        makePlanningTransitionPostgres()
+        makePlanningLinkPostgres()
+        makePlanningSchemaPostgres()
+      }
+      const names = (alias: string) => getDeclaration(alias).indexes.map(index => index.name).sort()
+
+      expect(names(RES_PLANNING_CARD)).toEqual([
+        'planning_card_code', 'planning_card_entity_intrinsic', 'planning_card_entity_kind_type', 'planning_card_labels',
+        'planning_card_parent_order', 'planning_card_parent_status', 'planning_card_parents', 'planning_card_slot',
+      ])
+      expect(names(RES_PLANNING_TRANSITION)).toEqual([
+        'planning_transition_card_seq', 'planning_transition_entity_key', 'planning_transition_pending', 'planning_transition_project_at',
+      ])
+      expect(names(RES_PLANNING_LINK)).toEqual([
+        'planning_link_edge', 'planning_link_entity_type', 'planning_link_inbound', 'planning_link_project',
+      ])
+      expect(names(RES_PLANNING_SCHEMA)).toEqual(['planning_schema_rev', 'planning_schema_scope'])
+
+      schemaToTableSpec(RES_PLANNING_CARD, PlanningCardTableSchema, 'app', 'planning_card', true, getDeclaration(RES_PLANNING_CARD).indexes)
+      expect(warn).not.toHaveBeenCalled()
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  test('the unique and partial indexes the store relies on', () => {
+    const find = (alias: string, name: string) => getDeclaration(alias).indexes.find(index => index.name === name)
+
+    expect(find(RES_PLANNING_TRANSITION, 'planning_transition_card_seq')).toMatchObject({ columns: ['card', 'seq'], unique: true })
+    expect(find(RES_PLANNING_TRANSITION, 'planning_transition_entity_key')).toMatchObject({ unique: true, where: '"key" IS NOT NULL' })
+    expect(find(RES_PLANNING_TRANSITION, 'planning_transition_pending')?.where).toContain(`'pending'`)
+    expect(find(RES_PLANNING_LINK, 'planning_link_edge')).toMatchObject({ columns: ['from', 'to', 'type'], unique: true })
+    expect(find(RES_PLANNING_SCHEMA, 'planning_schema_scope')).toMatchObject({ unique: true })
+    expect(find(RES_PLANNING_CARD, 'planning_card_parents')?.method).toBe('gin')
+  })
+})

package/tests/sql.spec.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from 'bun:test'
+import { schemaToTableSpec } from '@owlmeans/postgres-resource'
+
+import {
+  insertOf, pgFault, planningChannel, PlanningLinkTableSchema, PlanningPostgresError, RES_PLANNING_LINK, whereOf,
+} from '../src/index.js'
+
+const links = schemaToTableSpec(RES_PLANNING_LINK, PlanningLinkTableSchema, 'app', 'planning_link', true)
+
+describe('@owlmeans/planning-postgres — statements', () => {
+  test('a fixed-field where binds every value and reads a list as = ANY', () => {
+    const where = whereOf(links, { entityId: 'library-1', from: ['a', 'b'], to: undefined, type: 'sequel-of' }, 2)
+
+    expect(where.text).toBe('"entityId" = $3 AND "from" = ANY($4) AND "type" = $5')
+    expect(where.params).toEqual(['library-1', ['a', 'b'], 'sequel-of'])
+    expect(whereOf(links, {}).text).toBe('TRUE')
+  })
+
+  test('an insert names every column, JSON-encodes jsonb and binds absence as null', () => {
+    const insert = insertOf(links, {
+      id: 'l1', entityId: 'library-1', type: 'sequel-of', from: 'b2', to: 'b1', fields: { shelf: 3 }, createdAt: '2026-01-01T00:00:00.000Z',
+    }, { tail: 'RETURNING *' })
+
+    expect(insert.text).toStartWith(`INSERT INTO "app"."planning_link" (`)
+    expect(insert.text).toEndWith(' RETURNING *')
+    expect(insert.params).toContain('{"shelf":3}')
+    expect(insert.params.filter(value => value === null)).toHaveLength(2)
+  })
+
+  test('a driver fault is read through its cause chain', () => {
+    const driver = Object.assign(new Error('duplicate key'), { code: '23505', constraint: 'planning_link_edge' })
+    const wrapped = Object.assign(new Error('query failed'), { cause: driver })
+
+    expect(pgFault(wrapped)).toEqual({ code: '23505', constraint: 'planning_link_edge' })
+    expect(pgFault(new Error('plain'))).toEqual({})
+  })
+
+  test('the channel is a short identifier of the qualified table, different per schema', () => {
+    const first = planningChannel('"branch_a"."planning_transition"')
+    const second = planningChannel('"branch_b"."planning_transition"')
+
+    expect(first).toMatch(/^planning_[0-9a-f]{16}$/)
+    expect(first).not.toBe(second)
+    expect(planningChannel('"branch_a"."planning_transition"')).toBe(first)
+  })
+
+  test('its faults carry the package marker', () => {
+    expect(new PlanningPostgresError('resource-missing:planning-card').message).toBe('planning-postgres:resource-missing:planning-card')
+  })
+})

package/tests/sync.spec.ts

@@ -0,0 +1,61 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import { introspectTable, planSync } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import { createBranch, LIBRARY } from '@owlmeans/server-planning/conformance'
+
+import {
+  PlanningPostgresError, RES_PLANNING_CARD, RES_PLANNING_LINK, RES_PLANNING_SCHEMA, RES_PLANNING_TRANSITION,
+} from '../src/index.js'
+import { gate, makeSuite } from './context.js'
+
+const ALIASES = [RES_PLANNING_CARD, RES_PLANNING_TRANSITION, RES_PLANNING_LINK, RES_PLANNING_SCHEMA]
+
+const suite = makeSuite('sync')
+const it = gate.skip ? test.skip : test
+
+describe('@owlmeans/planning-postgres — tables and wiring', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  it('a second boot reconciles nothing on any of the four tables', async () => {
+    await suite.boot()
+    const again = await suite.boot()
+    const { pool } = await again.context.resource<PostgresResource<never>>(RES_PLANNING_CARD).db()
+    const client = await pool.connect()
+    try {
+      for (const alias of ALIASES) {
+        const table = again.context.resource<PostgresResource<never>>(alias).table
+        const live = await introspectTable(client, table.schema, table.table, table.qualified)
+        expect([alias, planSync(table, live).statements.map(statement => statement.sql)]).toEqual([alias, []])
+      }
+    } finally {
+      client.release()
+    }
+  })
+
+  it('names the file a missing resource is registered by', async () => {
+    const bare = await suite.boot({ wiring: 'none' })
+    const refusal = await bare.facade('library-1').execute({
+      card: { kind: WorkcardKind.Project, type: LIBRARY.branch, title: 'Nowhere to go' }, action: TransitionAction.Create,
+    }).catch(error => error)
+
+    expect(refusal).toBeInstanceOf(PlanningPostgresError)
+    expect(refusal.message).toBe('planning-postgres:resource-missing:planning-card: add src/resources/planning/card.ts')
+  })
+
+  it('appendPostgresPlanning registers the four resources and a working service in one call', async () => {
+    const appended = await suite.boot({ wiring: 'append' })
+
+    expect(ALIASES.every(alias => appended.context.hasResource(alias))).toBe(true)
+    const branch = await createBranch(appended.facade('library-2'), 'Appended branch')
+    expect((await appended.facade('library-2').cards.get(branch.id!)).title).toBe('Appended branch')
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": [
+      "bun"
+    ],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": [
+    "./**/*",
+    "../src/**/*"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}