@kelpie/server 0.7.0 → 0.8.0

package/src/modules/lists/repository.ts

@@ -0,0 +1,313 @@
+import { and, eq, ilike, inArray, sql } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import { containsPattern } from '../../lib/search.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import { listMembers, lists } from './schema.ts'
+
+export type ListRecord = typeof lists.$inferSelect
+export type ListColumns = typeof lists.$inferInsert
+
+export type ListMemberRecord = typeof listMembers.$inferSelect
+export type ListMemberColumns = typeof listMembers.$inferInsert
+
+/**
+ * The stored row with the rollup a UI index page needs. `member_count` is
+ * computed at read time rather than maintained on write so an unrelated bug
+ * cannot leave the count out of step with the actual rows.
+ */
+export type ListWithCount = ListRecord & { readonly memberCount: number }
+
+export const LIST_SORTS: SortableFields<ListWithCount> = {
+  name: textSort(lists.name, (list) => list.name),
+  created_at: timestampSort(lists.createdAt, (list) => list.createdAt),
+  updated_at: timestampSort(lists.updatedAt, (list) => list.updatedAt),
+}
+
+export const DEFAULT_LIST_SORT = '-updated_at'
+
+export interface ListFilters {
+  readonly term?: string | undefined
+  readonly targetType?: RecordTargetType | undefined
+}
+
+function conditionsFor(workspaceId: string, filters: ListFilters): (SQL | undefined)[] {
+  const term = filters.term
+  const targetType = filters.targetType
+
+  return [
+    eq(lists.workspaceId, workspaceId),
+    term === undefined ? undefined : ilike(lists.name, containsPattern(term)),
+    targetType === undefined ? undefined : eq(lists.targetType, targetType),
+  ]
+}
+
+/**
+ * @returns Up to `window.fetchLimit` rows: one more than the page, so the
+ *   caller can tell there is a next one. Each row carries the count of members
+ *   attached to it.
+ */
+export async function listLists(
+  db: Queryable,
+  workspaceId: string,
+  filters: ListFilters,
+  window: ListWindow<ListWithCount>,
+): Promise<ListWithCount[]> {
+  const rows = await db
+    .select()
+    .from(lists)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, lists.id)))
+    .orderBy(...orderByWindow(window, lists.id))
+    .limit(window.fetchLimit)
+
+  const counts = await countMembersFor(db, rows.map((row) => row.id))
+
+  return rows.map((row) => ({ ...row, memberCount: counts.get(row.id) ?? 0 }))
+}
+
+async function countMembersFor(
+  db: Queryable,
+  listIds: readonly string[],
+): Promise<ReadonlyMap<string, number>> {
+  if (listIds.length === 0) {
+    return new Map()
+  }
+
+  const rows = await db
+    .select({ listId: listMembers.listId, count: sql<number>`count(*)::int` })
+    .from(listMembers)
+    .where(inArray(listMembers.listId, [...listIds]))
+    .groupBy(listMembers.listId)
+
+  return new Map(rows.map((row) => [row.listId, Number(row.count)]))
+}
+
+export async function findList(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<ListWithCount | undefined> {
+  const [found] = await db
+    .select()
+    .from(lists)
+    .where(and(eq(lists.workspaceId, workspaceId), eq(lists.id, id)))
+    .limit(1)
+
+  if (found === undefined) {
+    return undefined
+  }
+
+  return { ...found, memberCount: await countMembers(db, id) }
+}
+
+async function countMembers(db: Queryable, listId: string): Promise<number> {
+  const [row] = await db
+    .select({ count: sql<number>`count(*)::int` })
+    .from(listMembers)
+    .where(eq(listMembers.listId, listId))
+
+  return Number(row?.count ?? 0)
+}
+
+export async function insertList(db: Queryable, values: ListColumns): Promise<ListRecord> {
+  const [created] = await db.insert(lists).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting list ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateList(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<ListColumns>,
+): Promise<ListRecord | undefined> {
+  const [updated] = await db
+    .update(lists)
+    .set(changes)
+    .where(and(eq(lists.workspaceId, workspaceId), eq(lists.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteList(db: Queryable, workspaceId: string, id: string): Promise<number> {
+  const deleted = await db
+    .delete(lists)
+    .where(and(eq(lists.workspaceId, workspaceId), eq(lists.id, id)))
+    .returning({ id: lists.id })
+
+  return deleted.length
+}
+
+/** Members: no cursor pagination yet. A list's members render on one page today. */
+
+export const LIST_MEMBER_SORTS: SortableFields<ListMemberRecord> = {
+  added_at: timestampSort(listMembers.addedAt, (row) => row.addedAt),
+}
+
+export const DEFAULT_LIST_MEMBER_SORT = '-added_at'
+
+export interface ListMemberFilters {
+  readonly listId: string
+  readonly targetType?: RecordTargetType | undefined
+}
+
+function memberConditionsFor(
+  workspaceId: string,
+  filters: ListMemberFilters,
+): (SQL | undefined)[] {
+  const targetType = filters.targetType
+
+  return [
+    eq(listMembers.workspaceId, workspaceId),
+    eq(listMembers.listId, filters.listId),
+    targetType === undefined ? undefined : eq(listMembers.targetType, targetType),
+  ]
+}
+
+export function listListMembers(
+  db: Queryable,
+  workspaceId: string,
+  filters: ListMemberFilters,
+  window: ListWindow<ListMemberRecord>,
+): Promise<ListMemberRecord[]> {
+  return db
+    .select()
+    .from(listMembers)
+    .where(and(...memberConditionsFor(workspaceId, filters), keysetCondition(window, listMembers.id)))
+    .orderBy(...orderByWindow(window, listMembers.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findListMember(
+  db: Queryable,
+  workspaceId: string,
+  listId: string,
+  id: string,
+): Promise<ListMemberRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(listMembers)
+    .where(
+      and(
+        eq(listMembers.workspaceId, workspaceId),
+        eq(listMembers.listId, listId),
+        eq(listMembers.id, id),
+      ),
+    )
+    .limit(1)
+
+  return found
+}
+
+export async function insertListMember(
+  db: Queryable,
+  values: ListMemberColumns,
+): Promise<ListMemberRecord> {
+  const [created] = await db.insert(listMembers).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting list_member ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function deleteListMember(
+  db: Queryable,
+  workspaceId: string,
+  listId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(listMembers)
+    .where(
+      and(
+        eq(listMembers.workspaceId, workspaceId),
+        eq(listMembers.listId, listId),
+        eq(listMembers.id, id),
+      ),
+    )
+    .returning({ id: listMembers.id })
+
+  return deleted.length
+}
+
+/** A membership row enriched with the list it points at. */
+export interface MembershipWithList {
+  readonly id: string
+  readonly listId: string
+  readonly listName: string
+  readonly listTargetType: string
+  readonly targetType: string
+  readonly targetId: string
+  readonly addedAt: Date
+}
+
+/**
+ * "Which lists is this record on?"
+ *
+ * Ordered by list name so a record's Lists tab reads alphabetically and the
+ * order does not shift as memberships are added.
+ */
+export async function listMembershipsForTarget(
+  db: Queryable,
+  workspaceId: string,
+  targetType: string,
+  targetId: string,
+): Promise<MembershipWithList[]> {
+  return db
+    .select({
+      id: listMembers.id,
+      listId: listMembers.listId,
+      listName: lists.name,
+      listTargetType: lists.targetType,
+      targetType: listMembers.targetType,
+      targetId: listMembers.targetId,
+      addedAt: listMembers.addedAt,
+    })
+    .from(listMembers)
+    .innerJoin(lists, eq(listMembers.listId, lists.id))
+    .where(
+      and(
+        eq(listMembers.workspaceId, workspaceId),
+        eq(listMembers.targetType, targetType),
+        eq(listMembers.targetId, targetId),
+      ),
+    )
+    .orderBy(lists.name)
+}
+
+/**
+ * Removes every list membership for one target.
+ *
+ * The target is polymorphic and carries no foreign key of its own, so nothing
+ * in the database deletes these when the target goes. The service that deletes
+ * the target calls this inside the same transaction.
+ */
+export async function deleteMembershipsForTarget(
+  db: Queryable,
+  workspaceId: string,
+  targetType: string,
+  targetId: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(listMembers)
+    .where(
+      and(
+        eq(listMembers.workspaceId, workspaceId),
+        eq(listMembers.targetType, targetType),
+        eq(listMembers.targetId, targetId),
+      ),
+    )
+    .returning({ id: listMembers.id })
+
+  return deleted.length
+}

package/src/modules/lists/routes.ts

@@ -0,0 +1,247 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError } from '../../lib/errors.ts'
+import { pageBody, readJsonBody, readListParameters } from '../../lib/http.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import { isRecordTargetType } from '../recordTargets.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import { RECORD_TARGET_TYPES } from './schema.ts'
+import type {
+  AddListMemberInput,
+  CreateListInput,
+  ListMemberView,
+  ListMembershipView,
+  ListView,
+  ListsService,
+  UpdateListInput,
+} from './service.ts'
+
+/**
+ * Wire shapes for `/v1/lists`.
+ *
+ * `target_type` is required on create and absent from update: a list's type is
+ * fixed for its lifetime. Bodies are strict, so a caller sending `target_type`
+ * on PATCH hears about it as a 422 rather than silently ignored.
+ */
+
+export const createBody = z.strictObject({
+  name: z.string().min(1),
+  target_type: z.enum(RECORD_TARGET_TYPES),
+  description: z.string().nullable().default(null),
+})
+
+export const updateBody = z
+  .strictObject({
+    name: z.string().min(1),
+    description: z.string().nullable(),
+  })
+  .partial()
+
+export const addMemberBody = z.strictObject({
+  target_type: z.enum(RECORD_TARGET_TYPES),
+  target_id: z.string().min(1),
+})
+
+export interface ListsRoutesDependencies extends CredentialDependencies {
+  readonly service: ListsService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateListInput {
+  return {
+    name: body.name,
+    targetType: body.target_type,
+    description: body.description,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateListInput {
+  return {
+    ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.description === undefined ? {} : { description: body.description }),
+  }
+}
+
+export function toAddMemberInput(body: z.infer<typeof addMemberBody>): AddListMemberInput {
+  return {
+    targetType: body.target_type,
+    targetId: body.target_id,
+  }
+}
+
+export function listResponse(list: ListView): Record<string, unknown> {
+  return {
+    id: list.id,
+    name: list.name,
+    description: list.description,
+    target_type: list.targetType,
+    member_count: list.memberCount,
+    created_at: list.createdAt.toISOString(),
+    updated_at: list.updatedAt.toISOString(),
+  }
+}
+
+export function listMembershipResponse(
+  membership: ListMembershipView,
+): Record<string, unknown> {
+  return {
+    id: membership.id,
+    list_id: membership.listId,
+    list_name: membership.listName,
+    list_target_type: membership.listTargetType,
+    target_type: membership.targetType,
+    target_id: membership.targetId,
+    added_at: membership.addedAt.toISOString(),
+  }
+}
+
+export function listMemberResponse(member: ListMemberView): Record<string, unknown> {
+  return {
+    id: member.id,
+    list_id: member.listId,
+    target_type: member.targetType,
+    target_id: member.targetId,
+    target_name: member.targetName,
+    added_at: member.addedAt.toISOString(),
+  }
+}
+
+function readTargetTypeFilter(context: Context): RecordTargetType | undefined {
+  const raw = context.req.query('target_type')
+
+  if (raw === undefined) {
+    return undefined
+  }
+
+  if (!isRecordTargetType(raw)) {
+    throw AppError.validationFailed('That is not a record type a list holds', [
+      { field: 'target_type', message: `Unknown target type "${raw}"` },
+    ])
+  }
+
+  return raw
+}
+
+function readMembershipTarget(context: Context): {
+  targetType: RecordTargetType
+  targetId: string
+} {
+  const rawType = context.req.query('target_type')
+  const targetId = context.req.query('target_id')
+
+  if (rawType === undefined || targetId === undefined || targetId.length === 0) {
+    throw AppError.validationFailed(
+      'A memberships list always names the record it is for',
+      [
+        { field: 'target_type', message: 'Required' },
+        { field: 'target_id', message: 'Required' },
+      ],
+    )
+  }
+
+  if (!isRecordTargetType(rawType)) {
+    throw AppError.validationFailed('That is not a record type a list holds', [
+      { field: 'target_type', message: `Unknown target type "${rawType}"` },
+    ])
+  }
+
+  return { targetType: rawType, targetId }
+}
+
+export function mountListsRoutes(router: Hono, dependencies: ListsRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> =>
+    resolveActorFrom(dependencies, context)
+
+  router.get('/list-memberships', async (context) => {
+    const { targetType, targetId } = readMembershipTarget(context)
+    const memberships = await dependencies.service.membershipsFor(
+      await requireActor(context),
+      targetType,
+      targetId,
+    )
+
+    // Not paged. A record has a small number of memberships in practice; the
+    // `next_cursor: null` is here so the standard list envelope reader accepts
+    // this response without a special case.
+    return context.json({
+      data: memberships.map(listMembershipResponse),
+      next_cursor: null,
+    })
+  })
+
+  router.get('/lists', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        targetType: readTargetTypeFilter(context),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, listResponse))
+  })
+
+  router.post('/lists', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const list = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(listResponse(list), 201)
+  })
+
+  router.get('/lists/:id', async (context) => {
+    const list = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(listResponse(list))
+  })
+
+  router.patch('/lists/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const list = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(listResponse(list))
+  })
+
+  router.delete('/lists/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+
+  router.get('/lists/:id/members', async (context) => {
+    const page = await dependencies.service.listMembers(
+      await requireActor(context),
+      { listId: context.req.param('id') },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, listMemberResponse))
+  })
+
+  router.post('/lists/:id/members', async (context) => {
+    const body = await readJsonBody(context, addMemberBody)
+    const member = await dependencies.service.addMember(
+      await requireActor(context),
+      context.req.param('id'),
+      toAddMemberInput(body),
+    )
+
+    return context.json(listMemberResponse(member), 201)
+  })
+
+  router.delete('/lists/:id/members/:memberId', async (context) => {
+    await dependencies.service.removeMember(
+      await requireActor(context),
+      context.req.param('id'),
+      context.req.param('memberId'),
+    )
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/lists/schema.ts

@@ -0,0 +1,85 @@
+import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { foreignKey, index, pgTable, text, timestamp, unique } from 'drizzle-orm/pg-core'
+
+import { checkOneOf, createdAt, primaryId, updatedAt } from '../../lib/columns.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * The target types come from `@kelpie/schemas`, so this check constraint, the
+ * route's Zod enum, and the browser's decoder are one list rather than three
+ * copies. Re-exported because `routes.ts` reads them from here, and the tables
+ * they constrain are the reason they matter.
+ */
+export { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+export type { RecordTargetType } from '@kelpie/schemas'
+
+/**
+ * A named collection of records of one type.
+ *
+ * The `target_type` is chosen at creation and never changes. A `list_members`
+ * row's `(list_id, target_type)` foreign-keys back into the composite unique on
+ * this table, so adding a person to a company list is refused by the database
+ * rather than trusted to the service.
+ *
+ * `(workspace_id, name)` is unique so the sidebar never shows two lists with the
+ * same label. Renaming to an in-use name returns 409.
+ */
+export const lists = pgTable(
+  'lists',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    description: text('description'),
+    targetType: text('target_type').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('lists_workspace_idx').on(table.workspaceId),
+    unique('lists_workspace_name_key').on(table.workspaceId, table.name),
+    // The referent of the composite FK from `list_members`. Postgres requires a
+    // unique key over the referenced columns; this exists solely to satisfy it.
+    unique('lists_id_target_type_key').on(table.id, table.targetType),
+    checkOneOf('lists_target_type_check', table.targetType, RECORD_TARGET_TYPES),
+  ],
+)
+
+/**
+ * A record's membership in a list.
+ *
+ * `(list_id, target_type)` foreign-keys back to the list's own unique key, so
+ * the member's type must equal its parent list's. The target itself is
+ * polymorphic and carries no foreign key of its own; the owning service checks
+ * existence with `missingTargets` and removes the row when the target goes
+ * (`attachedRecords.ts`).
+ */
+export const listMembers = pgTable(
+  'list_members',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    listId: text('list_id').notNull(),
+    targetType: text('target_type').notNull(),
+    targetId: text('target_id').notNull(),
+    // A membership is not edited, only added or removed, so no `updated_at`.
+    addedAt: timestamp('added_at', { withTimezone: true, mode: 'date' })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    index('list_members_list_idx').on(table.workspaceId, table.listId),
+    index('list_members_target_idx').on(table.workspaceId, table.targetType, table.targetId),
+    unique('list_members_list_target_key').on(table.listId, table.targetId),
+    foreignKey({
+      name: 'list_members_list_target_type_fk',
+      columns: [table.listId, table.targetType],
+      foreignColumns: [lists.id, lists.targetType],
+    }).onDelete('cascade'),
+    checkOneOf('list_members_target_type_check', table.targetType, RECORD_TARGET_TYPES),
+  ],
+)