@stacksjs/cms 0.70.53 → 0.70.55

package/src/taggables/fetch.ts

@@ -0,0 +1,282 @@
+import type { TaggableTable } from '@stacksjs/orm'
+import { getDb } from '../database'
+import { findOrCreate } from './store'
+
+/**
+ * Fetch a tag by its ID
+ *
+ * @param id The ID of the tag to fetch
+ * @returns The tag record if found
+ */
+export async function fetchTagById(id: number): Promise<TaggableTable | undefined> {
+  const db = await getDb()
+  try {
+    const result = await db
+      .selectFrom('taggables')
+      .where('id', '=', id)
+      .selectAll()
+      .executeTakeFirst()
+
+    if (!result) {
+      return undefined
+    }
+
+    return result as unknown as TaggableTable
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to fetch tag: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Fetch all tags
+ *
+ * @returns An array of tag records
+ */
+export async function fetchTags(): Promise<TaggableTable[]> {
+  const db = await getDb()
+  try {
+    return await db
+      .selectFrom('taggables')
+      .where('is_active', '=', true)
+      .selectAll()
+      .execute() as unknown as unknown as TaggableTable[]
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to fetch tags: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Find a tag by name or create it if it doesn't exist
+ *
+ * @param name The name of the tag to find or create
+ * @param taggableType Type of the taggable entity
+ * @param description Optional description for the tag
+ * @returns The existing or newly created tag
+ */
+export async function firstOrCreate(
+  name: string,
+  taggableType: string,
+  description?: string,
+): Promise<TaggableTable> {
+  try {
+    return await findOrCreate({
+      name,
+      taggable_type: taggableType,
+      description,
+    })
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to find or create tag: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Count the number of posts that have been tagged
+ *
+ * @param taggableType The type of entity to count (e.g. 'posts')
+ * @returns The count of tagged posts
+ */
+export async function countTaggedPosts(taggableType: string): Promise<number> {
+  const db = await getDb()
+  try {
+    const result = await db
+      .selectFrom('taggable_models')
+      .where('taggable_type', '=', taggableType)
+      .count()
+
+    return Number(result) || 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to count tagged posts: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Count the total number of tags in the system
+ *
+ * @returns The total count of tags
+ */
+export async function countTotalTags(): Promise<number> {
+  const db = await getDb()
+  try {
+    const result = await db
+      .selectFrom('taggables')
+      .count()
+
+    return Number(result) || 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to count total tags: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Find the most used tag in the system
+ *
+ * @param taggableType Optional type to filter by (e.g. 'posts', 'articles')
+ * @returns The most used tag name and its count
+ */
+export async function findMostUsedTag(taggableType?: string): Promise<{ name: string, count: number } | null> {
+  const db = await getDb()
+  try {
+    let query = db
+      .selectFrom('taggable_models')
+      .innerJoin('taggables', 'taggables.id', '=', 'taggable_models.tag_id')
+      .select([
+        'taggables.name',
+      ])
+      .groupBy('taggables.name') as any
+
+    if (taggableType)
+      query = query.where('taggable_models.taggable_type', '=', taggableType)
+
+    const result = await query
+      .orderBy('taggables.name', 'asc')
+      .executeTakeFirst()
+
+    if (!result) {
+      return null
+    }
+
+    return {
+      name: (result as Record<string, unknown>).name as string,
+      count: Number((result as Record<string, unknown>).usage_count || 0),
+    }
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to find most used tag: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Find the least used tag in the system
+ *
+ * @returns The least used tag name and its count
+ */
+export async function findLeastUsedTag(): Promise<{ name: string, count: number } | null> {
+  const db = await getDb()
+  try {
+    const result = await (db
+      .selectFrom('taggable_models')
+      .innerJoin('taggables', 'taggables.id', '=', 'taggable_models.tag_id')
+      .select([
+        'taggables.name',
+      ])
+      .groupBy('taggables.name') as any)
+      .orderBy('taggables.name', 'asc')
+      .executeTakeFirst()
+
+    if (!result) {
+      return null
+    }
+
+    return {
+      name: (result as Record<string, unknown>).name as string,
+      count: Number((result as Record<string, unknown>).usage_count || 0),
+    }
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to find least used tag: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Fetch tags with their post counts
+ *
+ * @returns Array of tags with their post counts
+ */
+export async function fetchTagsWithPostCounts(): Promise<Array<{ name: string, postCount: number }>> {
+  const db = await getDb()
+  try {
+    const result = await (db
+      .selectFrom('taggables')
+      .leftJoin('taggable_models', 'taggables.id', '=', 'taggable_models.tag_id')
+      .select([
+        'taggables.name',
+      ])
+      .groupBy('taggables.name') as any)
+      .orderBy('taggables.name', 'desc')
+      .limit(10)
+      .execute()
+
+    return (result as Record<string, unknown>[]).map((row: Record<string, unknown>) => ({
+      name: row.name as string,
+      postCount: Number(row.post_count || 0),
+    }))
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to fetch tags with post counts: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Fetch tag distribution data for a donut graph
+ *
+ * @returns Array of tags with their counts and percentages
+ */
+export async function fetchTagDistribution(): Promise<Array<{ name: string, count: number, percentage: number }>> {
+  const db = await getDb()
+  try {
+    const result = await (db
+      .selectFrom('taggables')
+      .leftJoin('taggable_models', 'taggables.id', '=', 'taggable_models.tag_id')
+      .select([
+        'taggables.name',
+      ])
+      .groupBy('taggables.name') as any)
+      .orderBy('taggables.name', 'desc')
+      .execute()
+
+    const typedResult = result as Record<string, unknown>[]
+
+    // Calculate total count for percentage calculation
+    const totalCount = typedResult.reduce((sum: number, row: Record<string, unknown>) => sum + Number(row.count || 0), 0)
+
+    return typedResult.map((row: Record<string, unknown>) => ({
+      name: row.name as string,
+      count: Number(row.count || 0),
+      percentage: totalCount > 0 ? (Number(row.count || 0) / totalCount) * 100 : 0,
+    }))
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to fetch tag distribution: ${error.message}`)
+    }
+
+    throw error
+  }
+}

package/src/taggables/index.ts

@@ -0,0 +1,17 @@
+export {
+  bulkDestroy,
+  destroy,
+} from './destroy'
+
+export {
+  fetchTagById,
+  fetchTags,
+} from './fetch'
+
+export {
+  store,
+} from './store'
+
+export {
+  update,
+} from './update'

package/src/taggables/store.ts

@@ -0,0 +1,122 @@
+import type { TaggableTable } from '@stacksjs/orm'
+import { getDb } from '../database'
+import { slugify } from 'ts-slug'
+
+interface TagData {
+  name: string
+  description?: string
+  is_active?: boolean
+  taggable_id?: number
+  taggable_type: string
+}
+
+/**
+ * Find or create multiple tags by their names
+ *
+ * @param names Array of tag names to process
+ * @param taggableType The type of model these tags belong to
+ * @returns Array of tag IDs
+ */
+export async function findOrCreateMany(names: string[], taggableType: string): Promise<number[]> {
+  const tagIds: number[] = []
+
+  for (const name of names) {
+    const tag = await findOrCreate({ name, taggable_type: taggableType })
+    tagIds.push(tag.id!)
+  }
+
+  return tagIds
+}
+
+/**
+ * Find or create a single tag
+ *
+ * @param data The tag data
+ * @returns The found or created tag
+ */
+export async function findOrCreate(data: TagData): Promise<TaggableTable> {
+  const db = await getDb()
+  try {
+    // Try to find existing tag
+    const existingTag = await db
+      .selectFrom('taggables')
+      .selectAll()
+      .where('name', '=', data.name)
+      .executeTakeFirst()
+
+    if (existingTag)
+      return existingTag as unknown as TaggableTable
+
+    // If not found, create new tag
+    return await store(data)
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to find or create tag: ${error.message}`)
+    }
+    throw error
+  }
+}
+
+/**
+ * Create a new tag
+ *
+ * @param data The tag data to store
+ * @returns The newly created tag record
+ */
+export async function store(data: TagData): Promise<TaggableTable> {
+  const db = await getDb()
+  try {
+    if (!data.name || data.name.trim() === '') {
+      throw new Error('Tag name is required')
+    }
+
+    if (!data.taggable_type || data.taggable_type.trim() === '') {
+      throw new Error('Tag taggable_type is required')
+    }
+
+    const slug = slugify(data.name)
+
+    // Enforce unique slugs
+    const existingSlug = await db
+      .selectFrom('taggables')
+      .selectAll()
+      .where('slug', '=', slug)
+      .executeTakeFirst()
+
+    if (existingSlug) {
+      throw new Error(`Tag with unique slug "${slug}" already exists`)
+    }
+
+    const tagData: Record<string, unknown> = {
+      name: data.name,
+      slug,
+      description: data.description,
+      is_active: data.is_active ?? true,
+      taggable_type: data.taggable_type,
+    }
+
+    if (data.taggable_id !== undefined) {
+      tagData.taggable_id = data.taggable_id
+    }
+
+    const result = await db
+      .insertInto('taggables')
+      .values(tagData)
+      .returningAll()
+      .executeTakeFirst()
+
+    if (!result) {
+      throw new Error('Failed to create tag')
+    }
+
+    return result as unknown as TaggableTable
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to store tag: ${error.message}`)
+    }
+
+    throw error
+  }
+}

package/src/taggables/update.ts

@@ -0,0 +1,74 @@
+import type { TaggableTable } from '@stacksjs/orm'
+import { getDb } from '../database'
+import { uniqueSlug } from '@stacksjs/slug'
+
+interface UpdateTagData {
+  id: number
+  name?: string
+  slug?: string
+  description?: string
+  is_active?: boolean
+  taggable_id?: number
+  taggable_type?: string
+}
+
+/**
+ * Update a tag
+ *
+ * @param id The tag id
+ * @param data The tag data to update
+ * @returns The updated tag record
+ */
+export async function update(data: UpdateTagData): Promise<TaggableTable> {
+  const db = await getDb()
+  try {
+    const id = data.id
+
+    if (!id) {
+      throw new Error('Tag ID is required for update')
+    }
+
+    if (data.name !== undefined) {
+      if (data.name.trim() === '') {
+        throw new Error('Tag name cannot be empty')
+      }
+
+      const slug = await uniqueSlug(data.name, { table: 'taggables', column: 'slug' })
+
+      // Enforce unique slugs on update
+      const existingSlug = await db
+        .selectFrom('taggables')
+        .selectAll()
+        .where('slug', '=', slug)
+        .where('id', '!=', id)
+        .executeTakeFirst()
+
+      if (existingSlug) {
+        throw new Error(`Tag with unique slug "${slug}" already exists`)
+      }
+
+      data.slug = slug
+    }
+
+    // Remove id from the data to avoid updating it
+    const { id: _id, ...updateData } = data
+
+    const result = await db
+      .updateTable('taggables')
+      .set(updateData as unknown as Record<string, unknown>)
+      .where('id', '=', id)
+      .returningAll()
+      .executeTakeFirst()
+
+    if (!result)
+      throw new Error('Failed to update tag')
+
+    return result as unknown as TaggableTable
+  }
+  catch (error) {
+    if (error instanceof Error)
+      throw new TypeError(`Failed to update tag: ${error.message}`)
+
+    throw error
+  }
+}

package/src/tests/categorizables.test.ts

@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { refreshDatabase } from './setup'
+import { destroy } from '../categorizables/destroy'
+import { store } from '../categorizables/store'
+
+beforeEach(async () => {
+  await refreshDatabase()
+})
+
+describe('Category Module', () => {
+  describe('store', () => {
+    it('should create multiple categories for the same post', async () => {
+      const firstCategory = await store({
+        name: 'Technology',
+        description: 'Technology related content',
+        categorizable_type: 'posts',
+        is_active: true,
+      })
+
+      const secondCategory = await store({
+        name: 'Programming',
+        description: 'Programming related content',
+        categorizable_type: 'posts',
+        is_active: true,
+      })
+
+      expect(firstCategory).toBeDefined()
+      expect(secondCategory).toBeDefined()
+      expect(firstCategory?.categorizable_type).toBe(secondCategory?.categorizable_type)
+    })
+
+    it('should throw an error when trying to create a category with invalid data', async () => {
+      const categoryData = {
+        name: '', // Empty name should fail
+        description: '',
+        categorizable_type: '',
+        is_active: false,
+      }
+
+      try {
+        await store(categoryData)
+        expect(true).toBe(false) // This line should not be reached
+      }
+      catch (error) {
+        expect(error).toBeDefined()
+        expect(error instanceof Error).toBe(true)
+      }
+    })
+  })
+
+  describe('destroy', () => {
+    it('should throw an error when trying to delete a non-existent category', async () => {
+      const nonExistentId = 99999999
+
+      try {
+        await destroy(nonExistentId)
+        expect(true).toBe(false) // This line should not be reached
+      }
+      catch (error) {
+        expect(error).toBeDefined()
+        expect(error instanceof Error).toBe(true)
+        expect((error as Error).message).toContain(`Category with ID ${nonExistentId} not found`)
+      }
+    })
+  })
+})

package/src/tests/setup.ts

@@ -0,0 +1,120 @@
+/**
+ * CMS package test harness.
+ *
+ * This suite used to import `refreshDatabase` from
+ * `@stacksjs/testing/database`, which (pre-existing breakage) never
+ * worked from a package directory: `bun test` run from
+ * storage/framework/core/cms doesn't load the repo-root `.env`, so the
+ * driver fell back to mysql and the helper's dead kysely-era
+ * `sql\`...\`.execute(db)` calls threw in every `beforeEach`.
+ *
+ * Strategy (mirrors auth/tests/password-reset-revocation.test.ts): pin
+ * env to a throwaway SQLite file BEFORE any framework module loads,
+ * then hand-create the two trait tables the categorizables module
+ * touches. `categorizables`/`categorizable_models` are trait tables
+ * (created by the categorizable model trait, not a model definition),
+ * so there is no model file to derive them from.
+ *
+ * Wired up via this package's bunfig.toml `[test] preload`, so the
+ * env pin always lands before any test file's own imports evaluate.
+ */
+
+import { existsSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+const DB_PATH = join(tmpdir(), `stacks-cms-${process.pid}.sqlite`)
+process.env.DB_CONNECTION = 'sqlite'
+process.env.DB_DATABASE_PATH = DB_PATH
+process.env.APP_ENV = 'testing'
+
+// Dynamic import AFTER the env pin so the lazy `db` proxy and the
+// config loader can't capture a different connection first.
+const { acquireDbConfigLock, db, ensureDatabaseConfigLoaded, initializeDbConfig } = await import('@stacksjs/database')
+
+// Holds `initializeDbConfig`'s process-wide config mutex (stacksjs/stacks#1862)
+// for this module's entire lifetime — no `describe`/`afterAll` boundary exists
+// here (this is a shared fixture imported by many test files, not a test file
+// itself), so it's released on process exit alongside the file cleanup below.
+const releaseDbConfigLock = await acquireDbConfigLock()
+
+/**
+ * Drain the one-shot async config reload, then force our temp SQLite
+ * config so a late-resolving override can't re-point the shared `db`
+ * proxy at a different database mid-test.
+ */
+async function forceConfig(): Promise<void> {
+  await ensureDatabaseConfigLoaded()
+  initializeDbConfig({
+    app: { env: 'testing' },
+    database: {
+      default: 'sqlite',
+      connections: { sqlite: { database: DB_PATH, prefix: '' } },
+    },
+  })
+}
+
+// Stale file from a recycled pid would otherwise leak a previous run's
+// schema/rows into this one.
+for (const suffix of ['', '-wal', '-shm']) {
+  if (existsSync(`${DB_PATH}${suffix}`))
+    unlinkSync(`${DB_PATH}${suffix}`)
+}
+
+await forceConfig()
+
+await db.unsafe(`
+  CREATE TABLE IF NOT EXISTS categorizables (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name VARCHAR(255) NOT NULL,
+    slug VARCHAR(255) NOT NULL,
+    description TEXT,
+    categorizable_type VARCHAR(255) NOT NULL,
+    is_active BOOLEAN NOT NULL DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP
+  )
+`).execute()
+
+await db.unsafe(`
+  CREATE TABLE IF NOT EXISTS categorizable_models (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    category_id INTEGER NOT NULL,
+    categorizable_type VARCHAR(255) NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP
+  )
+`).execute()
+
+const tableNames = ['categorizables', 'categorizable_models']
+
+/**
+ * Wipe the trait tables between tests. DELETE (not DROP) keeps the
+ * schema warm.
+ */
+export async function refreshDatabase(): Promise<void> {
+  await forceConfig()
+  for (const table of tableNames) {
+    await db.unsafe(`DELETE FROM ${table}`).execute()
+  }
+}
+
+// Cleanup on process exit, NOT in an `afterAll`: when this module is
+// imported by a test file mid-run (e.g. `bun test tests/` from the
+// repo root, where the path filter also matches this suite), an
+// `afterAll` registered during module evaluation attaches to the FIRST
+// importing file's scope and unlinks the shared DB while later files'
+// connections still use it (SQLITE_IOERR_VNODE).
+process.on('exit', () => {
+  for (const suffix of ['', '-wal', '-shm']) {
+    try {
+      if (existsSync(`${DB_PATH}${suffix}`))
+        unlinkSync(`${DB_PATH}${suffix}`)
+    }
+    catch {
+      // Best effort — pid-named file in tmpdir, the OS reclaims it.
+    }
+  }
+  releaseDbConfigLock()
+})