betterstart-cli 0.0.102 → 0.0.104

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-create-content.ts

@@ -0,0 +1,157 @@
+export function renderGenCreateContentServerActionTemplate({
+  ctxTableVar,
+  ctxCacheInvalidationFn,
+  ctxCamelPlural,
+  ctxSingular,
+  kebabSingular,
+  snapshotImport,
+  lifecycleHookImport,
+  markdownImport,
+  createContext,
+  beforeHook,
+  createBeforePublishBlock,
+  slugSourceValue,
+  toKebabCase,
+  ctxHtmlCreateBlock,
+  ctxCreateMappings,
+  ctxHasHtmlOutputContent,
+  ctxHasDraftContent,
+  ctxPlural,
+  snapshotData,
+  ctxSingularText,
+  createResultContext,
+  afterHook,
+  createAfterPublishBlock,
+  ctxCamelSingular
+}: {
+  ctxTableVar: string
+  ctxCacheInvalidationFn: string
+  ctxCamelPlural: string
+  ctxSingular: string
+  kebabSingular: string
+  snapshotImport: string
+  lifecycleHookImport: string
+  markdownImport: string
+  createContext: string
+  beforeHook: string
+  createBeforePublishBlock: string
+  slugSourceValue: string
+  toKebabCase: string
+  ctxHtmlCreateBlock: string
+  ctxCreateMappings: string
+  ctxHasHtmlOutputContent: string
+  ctxHasDraftContent: string
+  ctxPlural: string
+  snapshotData: string
+  ctxSingularText: string
+  createResultContext: string
+  afterHook: string
+  createAfterPublishBlock: string
+  ctxCamelSingular: string
+}): string {
+  return `'use server'
+
+import db from '@admin/db'
+import { requireRole, UserRole } from '@admin/auth/middleware'
+import { ${ctxTableVar} } from '@admin/db/schema'
+import { desc } from 'drizzle-orm'
+import { ${ctxCacheInvalidationFn} } from 'next/cache'
+import { createEntityVersion, entityVersionsCacheTags } from '@admin/actions/entity-versions'
+import { ${ctxCamelPlural}CacheTags } from './types'
+import { get${ctxSingular}ById } from './get-${kebabSingular}-by-id'
+import { getTouchedFieldNames } from '@admin/utils/audit/get-touched-field-names'
+import {
+  get${ctxSingular}SlugRetryLimit,
+  is${ctxSingular}SlugConflict,
+  resolveUnique${ctxSingular}Slug,
+  ${snapshotImport}
+} from './helpers'
+${lifecycleHookImport}
+import type { ${ctxSingular}CreateInput, ${ctxSingular}CreateResult, ${ctxSingular} } from './types'${markdownImport}
+
+export async function create${ctxSingular}(input: ${ctxSingular}CreateInput): Promise<${ctxSingular}CreateResult> {
+  const actor = await requireRole([UserRole.ADMIN, UserRole.EDITOR])
+
+  try {
+    const actorId = actor.id
+    const now = new Date().toISOString()
+    const auditRequestMetadata = await getAuditRequestMetadata()
+    const changedFields = getTouchedFieldNames(input as unknown as Record<string, unknown>)
+    const lifecycleContext = ${createContext}
+    ${beforeHook}
+${createBeforePublishBlock}
+
+    let result: (typeof ${ctxTableVar}.$inferSelect)[] | null = null
+    for (let attempt = 0; attempt < get${ctxSingular}SlugRetryLimit(); attempt += 1) {
+      try {
+        result = await db.transaction(async (tx) => {
+          const maxSortOrderResult = await tx
+            .select({ maxOrder: ${ctxTableVar}.sortOrder })
+            .from(${ctxTableVar})
+            .orderBy(desc(${ctxTableVar}.sortOrder))
+            .limit(1)
+          const nextSortOrder = (maxSortOrderResult[0]?.maxOrder ?? 0) + 1
+          const resolvedSlug = await resolveUnique${ctxSingular}Slug(tx, {
+            requestedSlug: input.slug,
+            sourceValue: ${slugSourceValue},
+            fallbackPrefix: '${toKebabCase}'
+          })
+${ctxHtmlCreateBlock}
+          const createdRows = await tx.insert(${ctxTableVar}).values({
+${ctxCreateMappings},${ctxHasHtmlOutputContent}${ctxHasDraftContent}
+            sortOrder: nextSortOrder,
+            createdAt: now,
+            updatedAt: now,
+            createdBy: actorId,
+            updatedBy: actorId
+          }).returning()
+
+          const createdRow = createdRows[0]
+          if (createdRow?.id) {
+            await createEntityVersion(tx, {
+              entityType: '${ctxPlural}',
+              entityId: createdRow.id,
+              data: ${snapshotData},
+              createdBy: actorId
+            })
+          }
+
+          return createdRows
+        })
+        break
+      } catch (error) {
+        if (is${ctxSingular}SlugConflict(error) && attempt < get${ctxSingular}SlugRetryLimit() - 1) {
+          continue
+        }
+        throw error
+      }
+    }
+
+    if (!result) throw new Error('Failed to create ${ctxSingularText}')
+
+    const created${ctxSingular}Id = result[0]?.id
+    ${ctxCacheInvalidationFn}(${ctxCamelPlural}CacheTags.all)
+    if (created${ctxSingular}Id !== null && created${ctxSingular}Id !== undefined) {
+      ${ctxCacheInvalidationFn}(${ctxCamelPlural}CacheTags.byId(created${ctxSingular}Id))
+      ${ctxCacheInvalidationFn}(entityVersionsCacheTags.for('${ctxPlural}', created${ctxSingular}Id))
+    }
+    const created${ctxSingular} =
+      typeof created${ctxSingular}Id === 'string'
+        ? await get${ctxSingular}ById(created${ctxSingular}Id)
+        : null
+    const created${ctxSingular}Data = created${ctxSingular} ?? (result[0] as unknown as ${ctxSingular})
+    const created${ctxSingular}Context = ${createResultContext}
+    ${afterHook}
+${createAfterPublishBlock}
+
+    return {
+      success: true,
+      ${ctxCamelSingular}: created${ctxSingular}Data
+    }
+  } catch (error) {
+    console.error('Error creating ${ctxSingularText}:', error)
+    throw new Error(error instanceof Error ? error.message : 'Failed to create ${ctxSingularText}')
+  }
+}
+`
+}

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-create-select-option-content.ts

@@ -0,0 +1,134 @@
+export function renderGenCreateSelectOptionContentServerActionTemplate({
+  ctxSelectOptionsTableVar,
+  ctxCacheInvalidationFn,
+  ctxCamelSingular,
+  ctxSingular,
+  selectOptionStaticOptions,
+  ctxSingularText
+}: {
+  ctxSelectOptionsTableVar: string
+  ctxCacheInvalidationFn: string
+  ctxCamelSingular: string
+  ctxSingular: string
+  selectOptionStaticOptions: string
+  ctxSingularText: string
+}): string {
+  return `'use server'
+
+import { requireRole, UserRole } from '@admin/auth/middleware'
+import db from '@admin/db'
+import { ${ctxSelectOptionsTableVar} } from '@admin/db/schema'
+import { eq } from 'drizzle-orm'
+import { ${ctxCacheInvalidationFn} } from 'next/cache'
+import { ${ctxCamelSingular}SelectOptionsCacheTags } from './types'
+import type {
+  Create${ctxSingular}SelectOptionInput,
+  Create${ctxSingular}SelectOptionResult,
+  ${ctxSingular}SelectOption,
+  ${ctxSingular}SelectOptionFieldName
+} from './types'
+
+${selectOptionStaticOptions}
+
+function toSelectOptionValue(label: string): string {
+  const normalized = label
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return normalized || 'option'
+}
+
+async function resolveSelectOptionValue(
+  fieldName: ${ctxSingular}SelectOptionFieldName,
+  label: string
+): Promise<string> {
+  const baseValue = toSelectOptionValue(label)
+  const rows = await db
+    .select({ value: ${ctxSelectOptionsTableVar}.value })
+    .from(${ctxSelectOptionsTableVar})
+    .where(eq(${ctxSelectOptionsTableVar}.fieldName, fieldName))
+  const usedValues = new Set([
+    ...STATIC_SELECT_OPTIONS[fieldName].map((option) => option.value),
+    ...rows.map((row) => row.value)
+  ])
+
+  if (!usedValues.has(baseValue)) return baseValue
+
+  let suffix = 2
+  let value = \`\${baseValue}-\${suffix}\`
+  while (usedValues.has(value)) {
+    suffix += 1
+    value = \`\${baseValue}-\${suffix}\`
+  }
+
+  return value
+}
+
+export async function create${ctxSingular}SelectOption(
+  input: Create${ctxSingular}SelectOptionInput
+): Promise<Create${ctxSingular}SelectOptionResult> {
+  const actor = await requireRole([UserRole.ADMIN, UserRole.EDITOR])
+
+  try {
+    const label = input.label.trim()
+    if (!label) {
+      return { success: false, error: 'Option label is required' }
+    }
+
+    const staticMatch = STATIC_SELECT_OPTIONS[input.fieldName].find(
+      (option) => option.label.toLowerCase() === label.toLowerCase()
+    )
+    if (staticMatch) {
+      return {
+        success: true,
+        option: {
+          id: staticMatch.value,
+          fieldName: input.fieldName,
+          label: staticMatch.label,
+          value: staticMatch.value,
+          createdAt: '',
+          updatedAt: ''
+        }
+      }
+    }
+
+    const rows = await db
+      .select()
+      .from(${ctxSelectOptionsTableVar})
+      .where(eq(${ctxSelectOptionsTableVar}.fieldName, input.fieldName))
+    const existing = rows.find((row) => row.label.toLowerCase() === label.toLowerCase())
+    if (existing) {
+      return { success: true, option: existing as ${ctxSingular}SelectOption }
+    }
+
+    const actorId = actor.id
+    const now = new Date().toISOString()
+    const value = await resolveSelectOptionValue(input.fieldName, label)
+    const [option] = await db
+      .insert(${ctxSelectOptionsTableVar})
+      .values({
+        fieldName: input.fieldName,
+        label,
+        value,
+        createdAt: now,
+        updatedAt: now,
+        createdBy: actorId,
+        updatedBy: actorId
+      })
+      .returning()
+
+    ${ctxCacheInvalidationFn}(${ctxCamelSingular}SelectOptionsCacheTags.byField(input.fieldName))
+
+    return { success: true, option: option as ${ctxSingular}SelectOption }
+  } catch (error) {
+    console.error('Error creating ${ctxSingularText} select option:', error)
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to create option'
+    }
+  }
+}
+`
+}

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-delete-bulk-content.ts

@@ -0,0 +1,85 @@
+export function renderGenDeleteBulkContentServerActionTemplate({
+  ctxTableVar,
+  ctxCacheInvalidationFn,
+  ctxCamelPlural,
+  lifecycleHookImport,
+  ctxSingular,
+  ctxPlural,
+  ctxPluralText,
+  beforeHook,
+  afterHook
+}: {
+  ctxTableVar: string
+  ctxCacheInvalidationFn: string
+  ctxCamelPlural: string
+  lifecycleHookImport: string
+  ctxSingular: string
+  ctxPlural: string
+  ctxPluralText: string
+  beforeHook: string
+  afterHook: string
+}): string {
+  return `'use server'
+
+import db from '@admin/db'
+import { requireRole, UserRole } from '@admin/auth/middleware'
+import { ${ctxTableVar} } from '@admin/db/schema'
+import { inArray } from 'drizzle-orm'
+import { ${ctxCacheInvalidationFn} } from 'next/cache'
+import { deleteEntityVersions, entityVersionsCacheTags } from '@admin/actions/entity-versions'
+import { ${ctxCamelPlural}CacheTags } from './types'
+${lifecycleHookImport}
+import type { ${ctxSingular}DeleteResult } from './types'
+
+export async function deleteBulk${ctxPlural}(ids: string[]): Promise<${ctxSingular}DeleteResult> {
+  const actor = await requireRole([UserRole.ADMIN, UserRole.EDITOR])
+  if (ids.length === 0) return { success: false, error: 'No items selected for deletion' }
+
+  const now = new Date().toISOString()
+  const auditRequestMetadata = await getAuditRequestMetadata()
+  const lifecycleContexts = ids.map((id) => ({
+    user: actor,
+    entityType: '${ctxPluralText}',
+    timestamp: now,
+    sourceType: 'admin_ui' as const,
+    ipAddress: auditRequestMetadata.ipAddress,
+    userAgent: auditRequestMetadata.userAgent,
+    entityId: id,
+    changedFields: []
+  }))
+
+  for (const lifecycleContext of lifecycleContexts) {
+    ${beforeHook}
+  }
+
+  try {
+    const deletedRows = await db.transaction(async (tx) => {
+      await deleteEntityVersions(tx, '${ctxPluralText}', ids)
+      return tx.delete(${ctxTableVar}).where(inArray(${ctxTableVar}.id, ids)).returning()
+    })
+    const deletedRowsById = new Map(
+      deletedRows.map((row) => [row.id, row as unknown as Record<string, unknown>])
+    )
+    ${ctxCacheInvalidationFn}(${ctxCamelPlural}CacheTags.all)
+    for (const id of ids) {
+      ${ctxCacheInvalidationFn}(${ctxCamelPlural}CacheTags.byId(id))
+      ${ctxCacheInvalidationFn}(entityVersionsCacheTags.for('${ctxPluralText}', id))
+    }
+    for (const lifecycleContext of lifecycleContexts) {
+      ${afterHook}
+    }
+    return { success: true }
+  } catch (error) {
+    console.error('Error deleting ${ctxPluralText}:', error)
+    return { success: false, error: error instanceof Error ? error.message : 'Failed to delete ${ctxPluralText}' }
+  }
+}
+`
+}
+
+export function renderGenDeleteBulkContentTemplate(): string {
+  return `{
+        ...lifecycleContext,
+        data: deletedRowsById.get(lifecycleContext.entityId)
+      }`
+}

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-delete-content.ts

@@ -0,0 +1,66 @@
+export function renderGenDeleteContentServerActionTemplate({
+  ctxTableVar,
+  ctxCacheInvalidationFn,
+  ctxCamelPlural,
+  lifecycleHookImport,
+  ctxSingular,
+  deleteContext,
+  beforeHook,
+  ctxPlural,
+  afterHook,
+  ctxSingularText
+}: {
+  ctxTableVar: string
+  ctxCacheInvalidationFn: string
+  ctxCamelPlural: string
+  lifecycleHookImport: string
+  ctxSingular: string
+  deleteContext: string
+  beforeHook: string
+  ctxPlural: string
+  afterHook: string
+  ctxSingularText: string
+}): string {
+  return `'use server'
+
+import db from '@admin/db'
+import { requireRole, UserRole } from '@admin/auth/middleware'
+import { ${ctxTableVar} } from '@admin/db/schema'
+import { eq } from 'drizzle-orm'
+import { ${ctxCacheInvalidationFn} } from 'next/cache'
+import { deleteEntityVersions, entityVersionsCacheTags } from '@admin/actions/entity-versions'
+import { ${ctxCamelPlural}CacheTags } from './types'
+${lifecycleHookImport}
+import type { ${ctxSingular}DeleteResult } from './types'
+
+export async function delete${ctxSingular}(id: string): Promise<${ctxSingular}DeleteResult> {
+  const actor = await requireRole([UserRole.ADMIN, UserRole.EDITOR])
+  const now = new Date().toISOString()
+  const auditRequestMetadata = await getAuditRequestMetadata()
+  const lifecycleContext = ${deleteContext}
+  ${beforeHook}
+
+  try {
+    const [deletedRow] = await db.transaction(async (tx) => {
+      await deleteEntityVersions(tx, '${ctxPlural}', [id])
+      return tx.delete(${ctxTableVar}).where(eq(${ctxTableVar}.id, id)).returning()
+    })
+    ${ctxCacheInvalidationFn}(${ctxCamelPlural}CacheTags.all)
+    ${ctxCacheInvalidationFn}(${ctxCamelPlural}CacheTags.byId(id))
+    ${ctxCacheInvalidationFn}(entityVersionsCacheTags.for('${ctxPlural}', id))
+    ${afterHook}
+    return { success: true }
+  } catch (error) {
+    console.error('Error deleting ${ctxSingularText}:', error)
+    return { success: false, error: error instanceof Error ? error.message : 'Failed to delete ${ctxSingularText}' }
+  }
+}
+`
+}
+
+export function renderGenDeleteContentTemplate(): string {
+  return `{
+      ...lifecycleContext,
+      data: deletedRow as unknown as Record<string, unknown> | undefined
+    }`
+}

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-distinct-files.ts

@@ -0,0 +1,45 @@
+export function renderGenDistinctFilesServerActionTemplate({
+  ctxTableVar,
+  ctxCacheReadImport,
+  ctxCamelPlural,
+  ctxPlural,
+  fieldPascal,
+  ctxCacheLifeLine,
+  filterField,
+  ctxPluralText
+}: {
+  ctxTableVar: string
+  ctxCacheReadImport: string
+  ctxCamelPlural: string
+  ctxPlural: string
+  fieldPascal: string
+  ctxCacheLifeLine: string
+  filterField: string
+  ctxPluralText: string
+}): string {
+  return `'use server'
+
+import db from '@admin/db'
+import { ${ctxTableVar} } from '@admin/db/schema'
+import { asc, isNotNull } from 'drizzle-orm'
+${ctxCacheReadImport}
+import { ${ctxCamelPlural}CacheTags } from './types'
+
+export async function getDistinct${ctxPlural}${fieldPascal}(): Promise<string[]> {
+  'use cache'${ctxCacheLifeLine}
+  cacheTag(${ctxCamelPlural}CacheTags.all)
+
+  try {
+    const results = await db
+      .selectDistinct({ value: ${ctxTableVar}.${filterField} })
+      .from(${ctxTableVar})
+      .where(isNotNull(${ctxTableVar}.${filterField}))
+      .orderBy(asc(${ctxTableVar}.${filterField}))
+    return results.map((r) => String(r.value)).filter(Boolean)
+  } catch (error) {
+    console.error('Error fetching distinct ${ctxPluralText} ${filterField}:', error)
+    return []
+  }
+}
+`
+}

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-get-by-id-content.ts

@@ -0,0 +1,55 @@
+export function renderGenGetByIdContentServerActionTemplate({
+  join,
+  joinText,
+  ctxCacheReadImport,
+  ctxCamelPlural,
+  ctxSingular,
+  populateImport,
+  authorshipAliasBlock,
+  ctxCacheLifeLine,
+  ctxSelectClause,
+  ctxTableVar,
+  ctxSingleRowReturn,
+  ctxSingularText
+}: {
+  join: string
+  joinText: string
+  ctxCacheReadImport: string
+  ctxCamelPlural: string
+  ctxSingular: string
+  populateImport: string
+  authorshipAliasBlock: string
+  ctxCacheLifeLine: string
+  ctxSelectClause: string
+  ctxTableVar: string
+  ctxSingleRowReturn: string
+  ctxSingularText: string
+}): string {
+  return `'use server'
+
+import db from '@admin/db'
+import { ${join} } from '@admin/db/schema'
+import { ${joinText} } from 'drizzle-orm'
+import { alias } from 'drizzle-orm/pg-core'
+${ctxCacheReadImport}
+import { ${ctxCamelPlural}CacheTags } from './types'
+import type { ${ctxSingular} } from './types'${populateImport}
+
+${authorshipAliasBlock}
+
+export async function get${ctxSingular}ById(id: string): Promise<${ctxSingular} | null> {
+  'use cache'${ctxCacheLifeLine}
+  cacheTag(${ctxCamelPlural}CacheTags.byId(id))
+  cacheTag(${ctxCamelPlural}CacheTags.all)
+
+  try {
+    const result = await ${ctxSelectClause}.where(eq(${ctxTableVar}.id, id)).limit(1)
+    if (result.length === 0) return null
+    ${ctxSingleRowReturn}
+  } catch (error) {
+    console.error('Error fetching ${ctxSingularText}:', error)
+    throw new Error('Failed to fetch ${ctxSingularText}')
+  }
+}
+`
+}

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-get-by-slug-content.ts

@@ -0,0 +1,55 @@
+export function renderGenGetBySlugContentServerActionTemplate({
+  join,
+  joinText,
+  ctxCacheReadImport,
+  ctxCamelPlural,
+  ctxSingular,
+  populateImport,
+  authorshipAliasBlock,
+  ctxCacheLifeLine,
+  ctxSelectClause,
+  ctxTableVar,
+  ctxSingleRowReturn,
+  ctxSingularText
+}: {
+  join: string
+  joinText: string
+  ctxCacheReadImport: string
+  ctxCamelPlural: string
+  ctxSingular: string
+  populateImport: string
+  authorshipAliasBlock: string
+  ctxCacheLifeLine: string
+  ctxSelectClause: string
+  ctxTableVar: string
+  ctxSingleRowReturn: string
+  ctxSingularText: string
+}): string {
+  return `'use server'
+
+import db from '@admin/db'
+import { ${join} } from '@admin/db/schema'
+import { ${joinText} } from 'drizzle-orm'
+import { alias } from 'drizzle-orm/pg-core'
+${ctxCacheReadImport}
+import { ${ctxCamelPlural}CacheTags } from './types'
+import type { ${ctxSingular} } from './types'${populateImport}
+
+${authorshipAliasBlock}
+
+export async function get${ctxSingular}BySlug(slug: string): Promise<${ctxSingular} | null> {
+  'use cache'${ctxCacheLifeLine}
+  cacheTag(${ctxCamelPlural}CacheTags.bySlug(slug))
+  cacheTag(${ctxCamelPlural}CacheTags.all)
+
+  try {
+    const result = await ${ctxSelectClause}.where(eq(${ctxTableVar}.slug, slug)).limit(1)
+    if (result.length === 0) return null
+    ${ctxSingleRowReturn}
+  } catch (error) {
+    console.error('Error fetching ${ctxSingularText} by slug:', error)
+    throw new Error('Failed to fetch ${ctxSingularText} by slug')
+  }
+}
+`
+}

package/dist/assets/adapters/next/templates/renderers/generators/actions/entity-file-contents/gen-get-plural-content.ts

@@ -0,0 +1,106 @@
+export function renderGenGetPluralContentServerActionTemplate({
+  join,
+  joinText,
+  ctxCacheReadImport,
+  ctxCamelPlural,
+  sort,
+  populateImport,
+  dateRangeHelper,
+  authorshipAliasBlock,
+  columnMapEntries,
+  ctxPlural,
+  ctxCacheLifeLine,
+  ctxSearchBlock,
+  ctxFilterConditions,
+  ctxListSelectClause,
+  ctxTableVar,
+  ctxWhere,
+  ctxListResultMapping,
+  ctxPluralText
+}: {
+  join: string
+  joinText: string
+  ctxCacheReadImport: string
+  ctxCamelPlural: string
+  sort: string
+  populateImport: string
+  dateRangeHelper: string
+  authorshipAliasBlock: string
+  columnMapEntries: string
+  ctxPlural: string
+  ctxCacheLifeLine: string
+  ctxSearchBlock: string
+  ctxFilterConditions: string
+  ctxListSelectClause: string
+  ctxTableVar: string
+  ctxWhere: string
+  ctxListResultMapping: string
+  ctxPluralText: string
+}): string {
+  return `'use server'
+
+import db from '@admin/db'
+import { ${join} } from '@admin/db/schema'
+import { ${joinText} } from 'drizzle-orm'
+import { alias } from 'drizzle-orm/pg-core'
+${ctxCacheReadImport}
+import { ${ctxCamelPlural}CacheTags } from './types'
+import type { ${sort} } from './types'${populateImport}${dateRangeHelper}
+
+${authorshipAliasBlock}
+
+const SORTABLE_COLUMNS = {
+${columnMapEntries}
+} as const
+
+export async function get${ctxPlural}(query?: ${ctxPlural}Query): Promise<${ctxPlural}Page> {
+  'use cache'${ctxCacheLifeLine}
+  cacheTag(${ctxCamelPlural}CacheTags.all)
+
+  try {
+    const conditions = []
+${ctxSearchBlock}${ctxFilterConditions}
+
+    const baseQuery = ${ctxListSelectClause}
+
+    const sortColumn = query?.orderBy && query.orderBy in SORTABLE_COLUMNS
+      ? SORTABLE_COLUMNS[query.orderBy as keyof typeof SORTABLE_COLUMNS]
+      : ${ctxTableVar}.sortOrder
+    const sortFn = query?.orderDirection === 'desc' ? desc : asc
+    const orderClause = sortFn(sortColumn)
+
+    const orderedQuery = conditions.length > 0
+      ? baseQuery.where(and(...conditions)).orderBy(orderClause)
+      : baseQuery.orderBy(orderClause)
+
+    const rawLimit = query?.limit
+    const limit = typeof rawLimit === 'number'
+      ? Number.isFinite(rawLimit)
+        ? Math.max(1, rawLimit)
+        : 1
+      : undefined
+    const rawOffset = query?.offset
+    const offset = typeof rawOffset === 'number' && Number.isFinite(rawOffset)
+      ? Math.max(0, rawOffset)
+      : 0
+    const isPaginated = typeof limit === 'number'
+    let results: unknown[]
+    if (isPaginated) {
+      const paginatedQuery = offset > 0
+        ? orderedQuery.limit(limit).offset(offset)
+        : orderedQuery.limit(limit)
+      results = await paginatedQuery
+    } else {
+      results = await orderedQuery
+    }
+
+    const total = isPaginated
+      ? Number((await db.select({ count: sql\`count(*)\` }).from(${ctxTableVar})${ctxWhere})[0]?.count ?? 0)
+      : results.length${ctxListResultMapping}
+  } catch (error) {
+    console.error('Error fetching ${ctxPluralText}:', error)
+    throw new Error('Failed to fetch ${ctxPluralText}')
+  }
+}
+`
+}