@basicbenframework/create 0.1.0

package/template/src/client/pages/Routing.jsx

@@ -0,0 +1,207 @@
+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 Routing() {
+  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="Routing"
+        subtitle="API routes, controllers, and middleware"
+      />
+
+      <div className="space-y-6">
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Route Files</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Routes are defined in the <code>src/routes/</code> directory. Each file exports route definitions that map HTTP methods to handlers.
+          </p>
+
+          <CodeBlock title="src/routes/posts.js">
+{`import { PostController } from '../controllers/PostController.js'
+import { auth } from '../middleware/auth.js'
+
+export default [
+  { method: 'GET', path: '/api/posts', handler: PostController.index, middleware: [auth] },
+  { method: 'GET', path: '/api/posts/:id', handler: PostController.show },
+  { method: 'POST', path: '/api/posts', handler: PostController.store, middleware: [auth] },
+  { method: 'PUT', path: '/api/posts/:id', handler: PostController.update, middleware: [auth] },
+  { method: 'DELETE', path: '/api/posts/:id', handler: PostController.destroy, middleware: [auth] },
+]`}
+          </CodeBlock>
+
+          <CodeBlock title="Generate a route file">
+{`npx basicben make:route posts`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Controllers</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Controllers handle the business logic for your routes. They receive the request and return a response.
+          </p>
+
+          <CodeBlock title="src/controllers/PostController.js">
+{`import { db } from 'basicben'
+
+export const PostController = {
+  // GET /api/posts
+  index: async (req, res) => {
+    const posts = await (await db.table('posts'))
+      .where('user_id', req.user.id)
+      .orderBy('created_at', 'DESC')
+      .get()
+
+    return res.json({ posts })
+  },
+
+  // GET /api/posts/:id
+  show: async (req, res) => {
+    const post = await (await db.table('posts')).find(req.params.id)
+
+    if (!post) {
+      return res.status(404).json({ error: 'Post not found' })
+    }
+
+    return res.json({ post })
+  },
+
+  // POST /api/posts
+  store: async (req, res) => {
+    const { title, content } = req.body
+
+    const result = await (await db.table('posts')).insert({
+      title,
+      content,
+      user_id: req.user.id
+    })
+
+    return res.status(201).json({
+      id: result.lastInsertRowid
+    })
+  },
+
+  // PUT /api/posts/:id
+  update: async (req, res) => {
+    const { title, content } = req.body
+
+    await (await db.table('posts'))
+      .where('id', req.params.id)
+      .where('user_id', req.user.id)
+      .update({ title, content })
+
+    return res.json({ success: true })
+  },
+
+  // DELETE /api/posts/:id
+  destroy: async (req, res) => {
+    await (await db.table('posts'))
+      .where('id', req.params.id)
+      .where('user_id', req.user.id)
+      .delete()
+
+    return res.json({ success: true })
+  }
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="Generate a controller">
+{`npx basicben make:controller Post`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Middleware</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Middleware runs before your route handler. Use it for authentication, logging, validation, etc.
+          </p>
+
+          <CodeBlock title="src/middleware/auth.js">
+{`import { verifyToken } from 'basicben/auth'
+import { db } from 'basicben'
+
+export const auth = async (req, res, next) => {
+  const header = req.headers.authorization
+
+  if (!header?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Unauthorized' })
+  }
+
+  const token = header.slice(7)
+
+  try {
+    const payload = await verifyToken(token)
+    const user = await (await db.table('users')).find(payload.userId)
+
+    if (!user) {
+      return res.status(401).json({ error: 'Unauthorized' })
+    }
+
+    req.user = user
+    next()
+  } catch {
+    return res.status(401).json({ error: 'Invalid token' })
+  }
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="Generate middleware">
+{`npx basicben make:middleware auth`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Route Parameters</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Access URL parameters via <code>req.params</code> and query strings via <code>req.query</code>.
+          </p>
+
+          <CodeBlock title="Parameters and query strings">
+{`// Route: /api/posts/:id
+// URL: /api/posts/123?include=author
+
+export const show = async (req, res) => {
+  const { id } = req.params        // { id: '123' }
+  const { include } = req.query    // { include: 'author' }
+
+  // ...
+}`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Request Body</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            JSON request bodies are automatically parsed and available on <code>req.body</code>.
+          </p>
+
+          <CodeBlock title="Accessing request body">
+{`export const store = async (req, res) => {
+  const { title, content, published } = req.body
+
+  // Validate and use the data
+  if (!title) {
+    return res.status(400).json({ error: 'Title is required' })
+  }
+
+  // ...
+}`}
+          </CodeBlock>
+        </Card>
+      </div>
+    </div>
+  )
+}

package/template/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/template/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>
+  )
+}