@deessejs/collections 0.0.1

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@deessejs/collections",
+  "version": "0.0.1",
+  "description": "High-level abstraction layer built on top of Drizzle ORM",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./fields": {
+      "types": "./dist/fields/index.d.ts",
+      "import": "./dist/fields/index.mjs",
+      "require": "./dist/fields/index.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "import": "./dist/plugins/index.mjs",
+      "require": "./dist/plugins/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "drizzle-kit": "^0.22.0",
+    "drizzle-orm": "^0.31.2",
+    "pg": "^8.11.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@deessejs/type-testing": "^0.1.5",
+    "@neondatabase/serverless": "^1.0.2",
+    "@types/node": "^20.14.12",
+    "@types/pg": "^8.11.0",
+    "eslint": "^8.57.0",
+    "neon-serverless": "^0.5.3",
+    "tsup": "^8.2.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  },
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,38 @@
+/**
+ * PostgreSQL adapter configuration
+ */
+export type PgAdapterConfig = {
+  url: string
+  migrationsPath?: string
+}
+
+/**
+ * PostgreSQL adapter
+ */
+export interface PgAdapter {
+  type: 'postgres'
+  config: PgAdapterConfig
+}
+
+/**
+ * Database adapter type
+ */
+export type DatabaseAdapter = PgAdapter
+
+/**
+ * Creates a PostgreSQL adapter
+ *
+ * @example
+ * const adapter = pgAdapter({
+ *   url: 'postgres://user:pass@localhost:5432/db'
+ * })
+ */
+export const pgAdapter = (config: PgAdapterConfig): PgAdapter => {
+  return {
+    type: 'postgres',
+    config: {
+      url: config.url,
+      migrationsPath: config.migrationsPath ?? './migrations'
+    }
+  }
+}

package/src/collection.ts

@@ -0,0 +1,138 @@
+import type { FieldDefinition } from './field'
+
+/**
+ * Collection configuration
+ */
+export type CollectionConfig<T extends Record<string, unknown> = Record<string, unknown>> = {
+  slug: string
+  name?: string
+  fields: Record<string, FieldDefinition>
+  hooks?: CollectionHooks
+  dataType?: T
+}
+
+/**
+ * Operation types
+ */
+export type OperationType = 'create' | 'update' | 'delete' | 'read'
+
+/**
+ * Hook context base
+ */
+export type HookContextBase = {
+  collection: string
+  operation: OperationType
+}
+
+/**
+ * Before/After Operation context
+ */
+export type OperationHookContext = HookContextBase & {
+  data?: Record<string, unknown>
+  where?: Record<string, unknown>
+  result?: unknown
+}
+
+/**
+ * Before/After Create context
+ */
+export type CreateHookContext = HookContextBase & {
+  operation: 'create'
+  data: Record<string, unknown>
+  result?: unknown
+  db?: unknown
+}
+
+/**
+ * Before/After Update context
+ */
+export type UpdateHookContext = HookContextBase & {
+  operation: 'update'
+  data: Record<string, unknown>
+  where: Record<string, unknown>
+  previousData?: Record<string, unknown>
+  result?: unknown
+  db?: unknown
+}
+
+/**
+ * Before/After Delete context
+ */
+export type DeleteHookContext = HookContextBase & {
+  operation: 'delete'
+  where: Record<string, unknown>
+  previousData?: Record<string, unknown>
+  result?: unknown
+  db?: unknown
+}
+
+/**
+ * Before/After Read context
+ */
+export type ReadHookContext = HookContextBase & {
+  operation: 'read'
+  query?: Record<string, unknown>
+  result?: unknown[]
+  db?: unknown
+}
+
+/**
+ * Generic hook function type
+ */
+export type GenericHookFunction = (context: OperationHookContext) => Promise<void> | void
+export type CreateHookFunction = (context: CreateHookContext) => Promise<void> | void
+export type UpdateHookFunction = (context: UpdateHookContext) => Promise<void> | void
+export type DeleteHookFunction = (context: DeleteHookContext) => Promise<void> | void
+export type ReadHookFunction = (context: ReadHookContext) => Promise<void> | void
+
+/**
+ * Collection hooks
+ */
+export type CollectionHooks = {
+  beforeOperation?: GenericHookFunction[]
+  afterOperation?: GenericHookFunction[]
+  beforeCreate?: CreateHookFunction[]
+  afterCreate?: CreateHookFunction[]
+  beforeUpdate?: UpdateHookFunction[]
+  afterUpdate?: UpdateHookFunction[]
+  beforeDelete?: DeleteHookFunction[]
+  afterDelete?: DeleteHookFunction[]
+  beforeRead?: ReadHookFunction[]
+  afterRead?: ReadHookFunction[]
+}
+
+/**
+ * A collection definition
+ */
+export type Collection<T extends Record<string, unknown> = Record<string, unknown>> = {
+  slug: string
+  name?: string
+  fields: Record<string, FieldDefinition>
+  hooks?: CollectionHooks
+  dataType?: T
+}
+
+/**
+ * Creates a new collection
+ *
+ * @example
+ * export const users = collection({
+ *   slug: 'users',
+ *   name: 'Users',
+ *   fields: {
+ *     name: field({ fieldType: text }),
+ *     email: field({ fieldType: email, unique: true })
+ *   }
+ * })
+ */
+export const collection = <T extends Record<string, unknown> = Record<string, unknown>>(
+  config: CollectionConfig<T>
+): Collection<T> => {
+  return {
+    slug: config.slug,
+    name: config.name,
+    fields: config.fields,
+    hooks: config.hooks,
+    dataType: config.dataType
+  }
+}

package/src/config.ts

@@ -0,0 +1,134 @@
+import { Pool, type Pool as PoolType } from 'pg'
+import { drizzle } from 'drizzle-orm/node-postgres'
+
+import type { Collection } from './collection'
+import type { DatabaseAdapter } from './adapter'
+import { buildSchema } from './schema'
+
+/**
+ * Plugin interface
+ */
+export type Plugin = {
+  name: string
+  collections?: Record<string, Collection>
+  hooks?: Record<string, unknown[]>
+}
+
+/**
+ * Configuration options
+ */
+export type ConfigOptions<T extends Collection[] = []> = {
+  database: DatabaseAdapter
+  collections: T
+  plugins?: Plugin[]
+}
+
+/**
+ * Define config return type with inferred collection keys
+ *
+ * - collections: metadata only (slug, name, fields, hooks, dataType)
+ * - db: Drizzle instance with operations (via schema tables)
+ * - $meta: array of collection slugs and plugin names
+ */
+export type DefineConfigReturn<T extends Collection[] = []> = {
+  collections: {
+    [K in T[number] as K['slug']]: Collection
+  }
+  db: ReturnType<typeof drizzle<Record<string, unknown>>>
+  $meta: {
+    collections: T[number]['slug'][]
+    plugins: string[]
+  }
+}
+
+/**
+ * Creates the configuration for the data layer
+ *
+ * @example
+ * const adapter = pgAdapter({
+ *   url: process.env.DATABASE_URL!
+ * })
+ *
+ * export const { collections, db } = defineConfig({
+ *   database: adapter,
+ *   collections: [users, posts],
+ *   plugins: [timestampsPlugin()]
+ * })
+ *
+ * // collections: metadata only
+ * collections.users.slug     // 'users'
+ * collections.users.fields   // { name, email, ... }
+ *
+ * // db: Drizzle instance with operations
+ * await db.users.findMany()
+ * await db.users.insert(values)
+ */
+export const defineConfig = <T extends Collection[]>(
+  options: ConfigOptions<T>
+): DefineConfigReturn<T> => {
+  // Initialize the database connection based on adapter type
+  let pool: PoolType | null = null
+  let dbInstance: ReturnType<typeof drizzle<Record<string, unknown>>> | null = null
+
+  let schema: Record<string, unknown> = {}
+
+  if (options.database.type === 'postgres') {
+    // Create pool from adapter config
+    pool = new Pool({
+      connectionString: options.database.config.url
+    })
+
+    // Build schema from collections
+    schema = buildSchema(options.collections as Collection[])
+
+    // Create Drizzle instance with schema
+    dbInstance = drizzle(pool, { schema })
+  }
+
+  // Build collections map (metadata only)
+  const collectionsMap: Record<string, Collection> = {}
+  const collectionNames: string[] = []
+
+  for (const coll of options.collections) {
+    // Store only metadata (not operations)
+    collectionsMap[coll.slug] = {
+      slug: coll.slug,
+      name: coll.name,
+      fields: coll.fields,
+      hooks: coll.hooks,
+      dataType: coll.dataType
+    }
+    collectionNames.push(coll.slug)
+  }
+
+  // Build plugins map
+  const pluginNames: string[] = []
+  if (options.plugins) {
+    for (const plugin of options.plugins) {
+      pluginNames.push(plugin.name)
+
+      // Register plugin collections (metadata only)
+      if (plugin.collections) {
+        for (const [name, coll] of Object.entries(plugin.collections)) {
+          collectionsMap[name] = {
+            slug: coll.slug,
+            name: coll.name,
+            fields: coll.fields,
+            hooks: coll.hooks,
+            dataType: coll.dataType
+          }
+          collectionNames.push(name)
+        }
+      }
+    }
+  }
+
+  return {
+    collections: collectionsMap as DefineConfigReturn<T>['collections'],
+    db: dbInstance as DefineConfigReturn<T>['db'],
+    $meta: {
+      collections: collectionNames as DefineConfigReturn<T>['$meta']['collections'],
+      plugins: pluginNames
+    }
+  }
+}

package/src/field-type.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod'
+
+/**
+ * A field type instance (already configured)
+ */
+export type FieldTypeInstance = {
+  schema: z.ZodType
+  database: unknown
+}
+
+/**
+ * A field type creator (needs to be called to get instance)
+ */
+export type FieldTypeCreator = () => FieldTypeInstance
+
+/**
+ * Field type configuration
+ */
+export type FieldTypeConfig = {
+  schema: z.ZodType
+  database?: unknown
+}
+
+/**
+ * Creates a new field type
+ *
+ * @example
+ * const text = fieldType({
+ *   schema: z.string(),
+ *   database: { type: 'text' }
+ * })
+ *
+ * const textField = text() // Get instance
+ */
+export const fieldType = (config: FieldTypeConfig): (() => FieldTypeInstance) => {
+  return () => ({
+    schema: config.schema,
+    database: config.database ?? {}
+  })
+}

package/src/field.ts

@@ -0,0 +1,46 @@
+import type { FieldTypeInstance } from './field-type'
+
+/**
+ * Field configuration options
+ */
+export type FieldOptions = {
+  fieldType: FieldTypeInstance
+  required?: boolean
+  unique?: boolean
+  indexed?: boolean
+  default?: unknown
+  label?: string
+  description?: string
+}
+
+/**
+ * Creates a field definition
+ *
+ * @example
+ * name: field({ fieldType: text() })
+ * email: field({ fieldType: email(), unique: true })
+ */
+export const field = (config: FieldOptions): FieldDefinition => {
+  return {
+    fieldType: config.fieldType,
+    required: config.required ?? false,
+    unique: config.unique ?? false,
+    indexed: config.indexed ?? false,
+    default: config.default,
+    label: config.label,
+    description: config.description
+  }
+}
+
+/**
+ * A field definition
+ */
+export type FieldDefinition = {
+  fieldType: FieldTypeInstance
+  required: boolean
+  unique: boolean
+  indexed: boolean
+  default?: unknown
+  label?: string
+  description?: string
+}

package/src/fields/f.ts

@@ -0,0 +1,192 @@
+import { fieldType, type FieldTypeInstance } from '../field-type'
+import { z } from 'zod'
+
+/**
+ * Derive the database type string from a Zod schema
+ */
+const getItemType = (itemSchema: z.ZodType): string => {
+  if (itemSchema instanceof z.ZodString) return 'text'
+  if (itemSchema instanceof z.ZodNumber) return 'integer'
+  if (itemSchema instanceof z.ZodBoolean) return 'boolean'
+  if (itemSchema instanceof z.ZodDate) return 'timestamp'
+  if (itemSchema instanceof z.ZodEnum) return 'text'
+  if (itemSchema instanceof z.ZodArray) return 'array'
+  if (itemSchema instanceof z.ZodObject) return 'jsonb'
+  return 'text'
+}
+
+/**
+ * Field types namespace (like zod's z)
+ */
+export const f = {
+  /**
+   * Text field type
+   */
+  text: (): FieldTypeInstance => fieldType({
+    schema: z.string(),
+    database: { type: 'text' }
+  })(),
+
+  /**
+   * Email field type with built-in validation
+   */
+  email: (): FieldTypeInstance => fieldType({
+    schema: z.string().email(),
+    database: { type: 'text' }
+  })(),
+
+  /**
+   * URL field type with built-in validation
+   */
+  url: (): FieldTypeInstance => fieldType({
+    schema: z.string().url(),
+    database: { type: 'text' }
+  })(),
+
+  /**
+   * Number field type
+   */
+  number: (): FieldTypeInstance => fieldType({
+    schema: z.number(),
+    database: { type: 'integer' }
+  })(),
+
+  /**
+   * Boolean field type
+   */
+  boolean: (): FieldTypeInstance => fieldType({
+    schema: z.boolean(),
+    database: { type: 'boolean' }
+  })(),
+
+  /**
+   * Date field type (date only, no time)
+   */
+  date: (): FieldTypeInstance => fieldType({
+    schema: z.date(),
+    database: { type: 'date' }
+  })(),
+
+  /**
+   * Timestamp field type (date with time)
+   */
+  timestamp: (): FieldTypeInstance => fieldType({
+    schema: z.date(),
+    database: { type: 'timestamp' }
+  })(),
+
+  /**
+   * Creates a select field type
+   */
+  select: <T extends readonly [string, ...string[]]>(
+    options: T
+  ): FieldTypeInstance => fieldType({
+    schema: z.enum(options),
+    database: { type: 'text' }
+  })(),
+
+  /**
+   * JSON field type for storing JSON data
+   */
+  json: (schema?: z.ZodType): FieldTypeInstance => fieldType({
+    schema: schema ?? z.any(),
+    database: { type: 'jsonb' }
+  })(),
+
+  /**
+   * Array field type for storing lists
+   */
+  array: (itemSchema: z.ZodType): FieldTypeInstance => fieldType({
+    schema: z.array(itemSchema),
+    database: { type: 'array', itemType: getItemType(itemSchema) }
+  })(),
+
+  /**
+   * Creates a relation field type for foreign key relationships
+   */
+  relation: (options: {
+    collection: string
+    singular?: boolean
+    many?: boolean
+    through?: string
+  }): FieldTypeInstance => {
+    const isMany = options.many ?? false
+    const isSingular = options.singular ?? false
+
+    return fieldType({
+      schema: isMany ? z.array(z.string()) : z.string(),
+      database: {
+        type: 'integer',
+        references: options.collection,
+        through: options.through,
+        many: isMany,
+        singular: isSingular
+      }
+    })()
+  }
+}
+
+/**
+ * @deprecated Use f.text() instead
+ */
+export const text = f.text
+
+/**
+ * @deprecated Use f.email() instead
+ */
+export const email = f.email
+
+/**
+ * @deprecated Use f.url() instead
+ */
+export const url = f.url
+
+/**
+ * @deprecated Use f.number() instead
+ */
+export const number = f.number
+
+/**
+ * @deprecated Use f.boolean() instead
+ */
+export const boolean = f.boolean
+
+/**
+ * @deprecated Use f.date() instead
+ */
+export const date = f.date
+
+/**
+ * @deprecated Use f.timestamp() instead
+ */
+export const timestamp = f.timestamp
+
+/**
+ * @deprecated Use f.select() instead
+ */
+export const select = f.select
+
+/**
+ * @deprecated Use f.json() instead
+ */
+export const json = f.json
+
+/**
+ * @deprecated Use f.array() instead
+ */
+export const array = f.array
+
+/**
+ * @deprecated Use f.relation() instead
+ */
+export const relation = f.relation
+
+/**
+ * @deprecated Use f.relation instead
+ */
+export type RelationOptions = {
+  collection: string
+  singular?: boolean
+  many?: boolean
+  through?: string
+}

package/src/fields/index.ts

@@ -0,0 +1 @@
+export * from './f'

package/src/index.ts

@@ -0,0 +1,27 @@
+// Field type system
+export { fieldType, type FieldTypeInstance, type FieldTypeCreator, type FieldTypeConfig } from './field-type'
+
+// Field
+export { field, type FieldDefinition, type FieldOptions } from './field'
+
+// Built-in field types
+export { f } from './fields'
+export * from './fields'
+
+// Collection
+export { collection, type CollectionConfig, type Collection, type CollectionHooks, type OperationType, type CreateHookContext, type UpdateHookContext, type DeleteHookContext, type ReadHookContext, type OperationHookContext, type CreateHookFunction, type UpdateHookFunction, type DeleteHookFunction, type ReadHookFunction, type GenericHookFunction } from './collection'
+
+// Operations
+export * from './operations'
+
+// Adapter
+export { pgAdapter, type PgAdapter, type PgAdapterConfig, type DatabaseAdapter } from './adapter'
+
+// Schema
+export { buildSchema, buildTable } from './schema'
+
+// Migrations
+export { push, generate, migrate } from './migrations'
+
+// Config
+export { defineConfig, type Plugin, type ConfigOptions, type DefineConfigReturn } from './config'