@basicbenframework/core 0.1.0

package/my-test-app/src/client/pages/Testing.jsx

@@ -0,0 +1,251 @@
+import { useTheme } from '../components/ThemeContext'
+import { Card } from '../components/Card'
+import { PageHeader } from '../components/PageHeader'
+import { AppLayout } from '../layouts/AppLayout'
+import { DocsLayout } from '../layouts/DocsLayout'
+
+export function Testing() {
+  const { t } = useTheme()
+
+  const CodeBlock = ({ children, title }) => (
+    <div className="mt-4">
+      {title && <div className={`text-xs font-medium mb-2 ${t.muted}`}>{title}</div>}
+      <div className={`rounded-lg p-4 font-mono text-sm ${t.card} border ${t.border} overflow-x-auto`}>
+        <pre className={t.text}>{children}</pre>
+      </div>
+    </div>
+  )
+
+  return (
+    <div>
+      <PageHeader
+        title="Testing"
+        subtitle="Write and run tests with Vitest"
+      />
+
+      <div className="space-y-6">
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Overview</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            BasicBen uses Vitest for fast, modern testing. Tests are automatically discovered in files ending with <code>.test.js</code> or <code>.spec.js</code>.
+          </p>
+
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npm run test</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Run tests once</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npm run test:watch</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Run tests in watch mode</p>
+            </div>
+          </div>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Writing Tests</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Create test files alongside your code or in a <code>tests/</code> directory.
+          </p>
+
+          <CodeBlock title="src/utils/helpers.test.js">
+{`import { describe, it, expect } from 'vitest'
+import { formatDate, slugify } from './helpers'
+
+describe('formatDate', () => {
+  it('formats a date correctly', () => {
+    const date = new Date('2024-01-15')
+    expect(formatDate(date)).toBe('January 15, 2024')
+  })
+
+  it('handles invalid dates', () => {
+    expect(formatDate(null)).toBe('')
+  })
+})
+
+describe('slugify', () => {
+  it('converts text to a slug', () => {
+    expect(slugify('Hello World')).toBe('hello-world')
+    expect(slugify('This is a TEST')).toBe('this-is-a-test')
+  })
+
+  it('removes special characters', () => {
+    expect(slugify('Hello! World?')).toBe('hello-world')
+  })
+})`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Testing API Routes</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Test your API endpoints using the built-in test client.
+          </p>
+
+          <CodeBlock title="tests/api/posts.test.js">
+{`import { describe, it, expect, beforeEach } from 'vitest'
+import { testClient, resetDatabase } from 'basicben/testing'
+
+describe('POST /api/posts', () => {
+  beforeEach(async () => {
+    await resetDatabase()
+  })
+
+  it('creates a post when authenticated', async () => {
+    const { body, status } = await testClient
+      .post('/api/posts')
+      .auth(testUser)
+      .send({
+        title: 'Test Post',
+        content: 'This is a test'
+      })
+
+    expect(status).toBe(201)
+    expect(body.id).toBeDefined()
+  })
+
+  it('returns 401 when not authenticated', async () => {
+    const { status } = await testClient
+      .post('/api/posts')
+      .send({ title: 'Test' })
+
+    expect(status).toBe(401)
+  })
+
+  it('validates required fields', async () => {
+    const { body, status } = await testClient
+      .post('/api/posts')
+      .auth(testUser)
+      .send({})
+
+    expect(status).toBe(400)
+    expect(body.errors.title).toBeDefined()
+  })
+})`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Test Database</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Tests run against an isolated test database that resets between tests.
+          </p>
+
+          <CodeBlock title="Database helpers">
+{`import { resetDatabase, seedDatabase, factory } from 'basicben/testing'
+
+describe('User tests', () => {
+  beforeEach(async () => {
+    // Reset database to clean state
+    await resetDatabase()
+
+    // Optionally seed with test data
+    await seedDatabase()
+  })
+
+  it('can create users with factory', async () => {
+    // Create a user using the factory
+    const user = await factory.user.create({
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+
+    expect(user.id).toBeDefined()
+  })
+
+  it('can create multiple records', async () => {
+    // Create 5 posts for a user
+    const posts = await factory.post.createMany(5, {
+      user_id: testUser.id
+    })
+
+    expect(posts).toHaveLength(5)
+  })
+})`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Mocking</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Use Vitest's built-in mocking for external dependencies.
+          </p>
+
+          <CodeBlock title="Mocking modules">
+{`import { describe, it, expect, vi } from 'vitest'
+import { sendEmail } from './email'
+
+// Mock the email module
+vi.mock('./email', () => ({
+  sendEmail: vi.fn()
+}))
+
+describe('Registration', () => {
+  it('sends welcome email after registration', async () => {
+    await testClient
+      .post('/api/auth/register')
+      .send({
+        name: 'New User',
+        email: 'new@example.com',
+        password: 'password123'
+      })
+
+    expect(sendEmail).toHaveBeenCalledWith(
+      'new@example.com',
+      'Welcome!',
+      expect.any(String)
+    )
+  })
+})`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Code Coverage</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Generate code coverage reports to see what's tested.
+          </p>
+
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npm run test:coverage</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Run tests with coverage</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npm run test:ui</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Open Vitest UI</p>
+            </div>
+          </div>
+
+          <CodeBlock title="Coverage output">
+{`----------|---------|----------|---------|---------|
+File      | % Stmts | % Branch | % Funcs | % Lines |
+----------|---------|----------|---------|---------|
+All files |   85.71 |    78.26 |   90.00 |   85.71 |
+ auth.js  |  100.00 |   100.00 |  100.00 |  100.00 |
+ posts.js |   75.00 |    66.67 |   80.00 |   75.00 |
+----------|---------|----------|---------|---------|`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Testing Best Practices</h2>
+          <div className="space-y-3 mt-4">
+            {[
+              { title: 'Isolate tests', desc: 'Each test should be independent and not rely on other tests' },
+              { title: 'Reset state', desc: 'Use beforeEach to reset the database and any mocks' },
+              { title: 'Test behavior', desc: 'Test what the code does, not how it does it' },
+              { title: 'Use descriptive names', desc: 'Test names should describe the expected behavior' },
+              { title: 'Keep tests fast', desc: 'Mock external services and use test databases' },
+            ].map(({ title, desc }) => (
+              <div key={title} className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+                <div className="font-semibold text-sm">{title}</div>
+                <p className={`text-xs mt-1 ${t.muted}`}>{desc}</p>
+              </div>
+            ))}
+          </div>
+        </Card>
+      </div>
+    </div>
+  )
+}

package/my-test-app/src/client/pages/Validation.jsx

@@ -0,0 +1,210 @@
+import { useTheme } from '../components/ThemeContext'
+import { Card } from '../components/Card'
+import { PageHeader } from '../components/PageHeader'
+import { AppLayout } from '../layouts/AppLayout'
+import { DocsLayout } from '../layouts/DocsLayout'
+
+export function Validation() {
+  const { t } = useTheme()
+
+  const CodeBlock = ({ children, title }) => (
+    <div className="mt-4">
+      {title && <div className={`text-xs font-medium mb-2 ${t.muted}`}>{title}</div>}
+      <div className={`rounded-lg p-4 font-mono text-sm ${t.card} border ${t.border} overflow-x-auto`}>
+        <pre className={t.text}>{children}</pre>
+      </div>
+    </div>
+  )
+
+  return (
+    <div>
+      <PageHeader
+        title="Validation"
+        subtitle="Request validation with built-in rules"
+      />
+
+      <div className="space-y-6">
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Basic Usage</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Validate request data using the <code>validate</code> function and built-in rules.
+          </p>
+
+          <CodeBlock title="Validating request body">
+{`import { validate, rules } from 'basicben/validation'
+
+export const store = async (req, res) => {
+  const result = await validate(req.body, {
+    title: [rules.required, rules.minLength(3), rules.maxLength(100)],
+    email: [rules.required, rules.email],
+    age: [rules.required, rules.number, rules.min(18)]
+  })
+
+  if (!result.valid) {
+    return res.status(400).json({ errors: result.errors })
+  }
+
+  // Data is valid, continue...
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="Error response format">
+{`{
+  "errors": {
+    "title": ["Title is required"],
+    "email": ["Invalid email format"],
+    "age": ["Must be at least 18"]
+  }
+}`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Available Rules</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            BasicBen includes commonly used validation rules out of the box.
+          </p>
+
+          <div className="grid gap-2 sm:grid-cols-2">
+            {[
+              { rule: 'required', desc: 'Field must be present and not empty' },
+              { rule: 'email', desc: 'Must be a valid email address' },
+              { rule: 'number', desc: 'Must be a number' },
+              { rule: 'string', desc: 'Must be a string' },
+              { rule: 'boolean', desc: 'Must be true or false' },
+              { rule: 'array', desc: 'Must be an array' },
+              { rule: 'minLength(n)', desc: 'String must be at least n characters' },
+              { rule: 'maxLength(n)', desc: 'String must be at most n characters' },
+              { rule: 'min(n)', desc: 'Number must be at least n' },
+              { rule: 'max(n)', desc: 'Number must be at most n' },
+              { rule: 'regex(pattern)', desc: 'Must match the regex pattern' },
+              { rule: 'in(values)', desc: 'Must be one of the given values' },
+            ].map(({ rule, desc }) => (
+              <div key={rule} className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+                <code className="text-sm font-semibold">{rule}</code>
+                <p className={`text-xs mt-1 ${t.muted}`}>{desc}</p>
+              </div>
+            ))}
+          </div>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Database Rules</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Validate against your database with <code>unique</code> and <code>exists</code> rules.
+          </p>
+
+          <CodeBlock title="Unique validation">
+{`// Check if email is unique in users table
+email: [rules.required, rules.email, rules.unique('users')]
+
+// With custom column
+slug: [rules.unique('categories', 'slug')]
+
+// Exclude current record (for updates)
+email: [rules.unique('users', 'email', currentUserId)]`}
+          </CodeBlock>
+
+          <CodeBlock title="Exists validation">
+{`// Check if user_id exists in users table
+user_id: [rules.required, rules.exists('users')]
+
+// With custom column
+category: [rules.exists('categories', 'slug')]`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Custom Rules</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Create custom validation rules for specific requirements.
+          </p>
+
+          <CodeBlock title="Creating a custom rule">
+{`// Custom rule as a function
+const isSlug = (value, field) => {
+  if (!/^[a-z0-9-]+$/.test(value)) {
+    return \`\${field} must only contain lowercase letters, numbers, and hyphens\`
+  }
+  return null // Return null if valid
+}
+
+// Use it in validation
+const result = await validate(req.body, {
+  slug: [rules.required, isSlug]
+})`}
+          </CodeBlock>
+
+          <CodeBlock title="Async custom rule">
+{`// Async rule for complex validation
+const isAvailableUsername = async (value, field) => {
+  const existing = await (await db.table('users'))
+    .where('username', value)
+    .first()
+
+  if (existing) {
+    return 'Username is already taken'
+  }
+  return null
+}
+
+const result = await validate(req.body, {
+  username: [rules.required, isAvailableUsername]
+})`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Optional Fields</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Fields without the <code>required</code> rule are optional. Other rules only run if the field has a value.
+          </p>
+
+          <CodeBlock title="Optional field validation">
+{`const result = await validate(req.body, {
+  name: [rules.required],           // Required
+  bio: [rules.maxLength(500)],      // Optional, but if provided must be <= 500 chars
+  website: [rules.url]              // Optional, but if provided must be a valid URL
+})`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Nested Objects</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Validate nested objects using dot notation.
+          </p>
+
+          <CodeBlock title="Nested validation">
+{`// Request body: { user: { name: 'John', email: 'john@example.com' } }
+
+const result = await validate(req.body, {
+  'user.name': [rules.required, rules.minLength(2)],
+  'user.email': [rules.required, rules.email]
+})`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Custom Error Messages</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Override default error messages with custom ones.
+          </p>
+
+          <CodeBlock title="Custom messages">
+{`const result = await validate(req.body, {
+  email: [
+    { rule: rules.required, message: 'Please enter your email' },
+    { rule: rules.email, message: 'Please enter a valid email address' }
+  ],
+  password: [
+    { rule: rules.required, message: 'Password is required' },
+    { rule: rules.minLength(8), message: 'Password must be at least 8 characters' }
+  ]
+})`}
+          </CodeBlock>
+        </Card>
+      </div>
+    </div>
+  )
+}

package/my-test-app/src/controllers/AuthController.js

@@ -0,0 +1,81 @@
+import { validate, rules } from '@basicbenframework/core/validation'
+import { signJwt, verifyJwt, hashPassword, verifyPassword } from '@basicbenframework/core/auth'
+import { User } from '../models/User.js'
+
+export const AuthController = {
+  async register(req, res) {
+    const result = await validate(req.body, {
+      name: [rules.required, rules.string, rules.min(2)],
+      email: [rules.required, rules.email],
+      password: [rules.required, rules.min(8)]
+    })
+
+    if (result.fails()) {
+      return res.json({ errors: result.errors }, 422)
+    }
+
+    const { name, email, password } = req.body
+
+    // Check if email exists
+    const existing = await User.findByEmail(email)
+    if (existing) {
+      return res.json({ error: 'Email already registered' }, 400)
+    }
+
+    // Create user
+    const user = await User.create({
+      name,
+      email,
+      password: await hashPassword(password)
+    })
+
+    // Generate token
+    const token = signJwt({ userId: user.id }, process.env.APP_KEY, { expiresIn: '7d' })
+
+    res.json({
+      user: { id: user.id, name: user.name, email: user.email },
+      token
+    })
+  },
+
+  async login(req, res) {
+    const { email, password } = req.body
+
+    if (!email || !password) {
+      return res.json({ error: 'Email and password required' }, 400)
+    }
+
+    const user = await User.findByEmail(email)
+    if (!user || !(await verifyPassword(password, user.password))) {
+      return res.json({ error: 'Invalid credentials' }, 401)
+    }
+
+    const token = signJwt({ userId: user.id }, process.env.APP_KEY, { expiresIn: '7d' })
+
+    res.json({
+      user: { id: user.id, name: user.name, email: user.email },
+      token
+    })
+  },
+
+  async user(req, res) {
+    const token = req.headers.authorization?.replace('Bearer ', '')
+    if (!token) {
+      return res.json({ error: 'No token provided' }, 401)
+    }
+
+    const payload = verifyJwt(token, process.env.APP_KEY)
+    if (!payload) {
+      return res.json({ error: 'Invalid token' }, 401)
+    }
+
+    const user = await User.find(payload.userId)
+    if (!user) {
+      return res.json({ error: 'User not found' }, 404)
+    }
+
+    res.json({
+      user: { id: user.id, name: user.name, email: user.email }
+    })
+  }
+}

package/my-test-app/src/controllers/HomeController.js

@@ -0,0 +1,17 @@
+/**
+ * Home Controller
+ *
+ * Handles basic application endpoints.
+ */
+
+export const HomeController = {
+  /**
+   * Hello endpoint
+   */
+  hello: async (req, res) => {
+    res.json({
+      message: 'Welcome to BasicBen!',
+      timestamp: new Date().toISOString()
+    })
+  }
+}

package/my-test-app/src/controllers/PostController.js

@@ -0,0 +1,86 @@
+import { validate, rules } from '@basicbenframework/core/validation'
+import { Post } from '../models/Post.js'
+
+export const PostController = {
+  async index(req, res) {
+    const posts = await Post.findByUser(req.userId)
+    res.json({ posts })
+  },
+
+  async show(req, res) {
+    const post = await Post.find(req.params.id)
+    if (!post || post.user_id !== req.userId) {
+      return res.json({ error: 'Post not found' }, 404)
+    }
+    res.json({ post })
+  },
+
+  async store(req, res) {
+    const result = await validate(req.body, {
+      title: [rules.required, rules.string, rules.min(3), rules.max(200)],
+      content: [rules.required, rules.string, rules.min(10)]
+    })
+
+    if (result.fails()) {
+      return res.json({ errors: result.errors }, 422)
+    }
+
+    const { title, content, published } = req.body
+    const post = await Post.create({
+      user_id: req.userId,
+      title,
+      content,
+      published: published || false
+    })
+
+    res.json({ post }, 201)
+  },
+
+  async update(req, res) {
+    const post = await Post.find(req.params.id)
+    if (!post || post.user_id !== req.userId) {
+      return res.json({ error: 'Post not found' }, 404)
+    }
+
+    const result = await validate(req.body, {
+      title: [rules.required, rules.string, rules.min(3), rules.max(200)],
+      content: [rules.required, rules.string, rules.min(10)]
+    })
+
+    if (result.fails()) {
+      return res.json({ errors: result.errors }, 422)
+    }
+
+    const { title, content, published } = req.body
+    const updated = await Post.update(req.params.id, {
+      title,
+      content,
+      published: published ? 1 : 0
+    })
+
+    res.json({ post: updated })
+  },
+
+  async destroy(req, res) {
+    const post = await Post.find(req.params.id)
+    if (!post || post.user_id !== req.userId) {
+      return res.json({ error: 'Post not found' }, 404)
+    }
+
+    await Post.delete(req.params.id)
+    res.json({ message: 'Post deleted' })
+  },
+
+  async feed(req, res) {
+    const posts = await Post.findPublished()
+    res.json({ posts })
+  },
+
+  async feedShow(req, res) {
+    const post = await Post.findPublishedById(req.params.id)
+    if (!post) {
+      return res.json({ error: 'Post not found' }, 404)
+    }
+    res.json({ post })
+  }
+}