@basicbenframework/core 0.1.0

package/create-basicben-app/template/src/client/pages/Authentication.jsx

@@ -0,0 +1,236 @@
+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 Authentication() {
+  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="Authentication"
+        subtitle="JWT auth, password hashing, and protected routes"
+      />
+
+      <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 includes a complete JWT-based authentication system with password hashing, token generation, and middleware for protected routes.
+          </p>
+
+          <div className="grid gap-3 sm:grid-cols-3">
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">JWT Tokens</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Stateless authentication</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">Bcrypt Hashing</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Secure password storage</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">Auth Middleware</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Protect your routes</p>
+            </div>
+          </div>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Password Hashing</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Use bcrypt to securely hash and verify passwords.
+          </p>
+
+          <CodeBlock title="Hash and verify passwords">
+{`import { hashPassword, verifyPassword } from 'basicben/auth'
+
+// Hash a password (for registration)
+const hashedPassword = await hashPassword('user-password')
+
+// Verify a password (for login)
+const isValid = await verifyPassword('user-password', hashedPassword)
+// Returns true or false`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">JWT Tokens</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Generate and verify JWT tokens for stateless authentication.
+          </p>
+
+          <CodeBlock title="Generate and verify tokens">
+{`import { generateToken, verifyToken } from 'basicben/auth'
+
+// Generate a token (after successful login)
+const token = await generateToken({ userId: user.id })
+
+// Verify a token (in middleware)
+try {
+  const payload = await verifyToken(token)
+  console.log(payload.userId) // The user ID from the token
+} catch (error) {
+  // Token is invalid or expired
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="Configure token expiration in basicben.config.js">
+{`export default {
+  auth: {
+    jwtSecret: process.env.JWT_SECRET,
+    jwtExpiresIn: '7d' // Token expires in 7 days
+  }
+}`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Registration</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Example registration endpoint that creates a user and returns a token.
+          </p>
+
+          <CodeBlock title="src/controllers/AuthController.js">
+{`import { db } from 'basicben'
+import { hashPassword, generateToken } from 'basicben/auth'
+import { validate, rules } from 'basicben/validation'
+
+export const AuthController = {
+  register: async (req, res) => {
+    // Validate input
+    const result = await validate(req.body, {
+      name: [rules.required, rules.minLength(2)],
+      email: [rules.required, rules.email, rules.unique('users')],
+      password: [rules.required, rules.minLength(8)]
+    })
+
+    if (!result.valid) {
+      return res.status(400).json({ errors: result.errors })
+    }
+
+    // Create user
+    const hashedPassword = await hashPassword(req.body.password)
+
+    const { lastInsertRowid } = await (await db.table('users')).insert({
+      name: req.body.name,
+      email: req.body.email,
+      password: hashedPassword
+    })
+
+    // Get the created user
+    const user = await (await db.table('users')).find(lastInsertRowid)
+
+    // Generate token
+    const token = await generateToken({ userId: user.id })
+
+    return res.status(201).json({
+      user: { id: user.id, name: user.name, email: user.email },
+      token
+    })
+  }
+}`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Login</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Example login endpoint that verifies credentials and returns a token.
+          </p>
+
+          <CodeBlock title="Login handler">
+{`import { verifyPassword, generateToken } from 'basicben/auth'
+
+export const AuthController = {
+  login: async (req, res) => {
+    const { email, password } = req.body
+
+    // Find user by email
+    const user = await (await db.table('users'))
+      .where('email', email)
+      .first()
+
+    if (!user) {
+      return res.status(401).json({ error: 'Invalid credentials' })
+    }
+
+    // Verify password
+    const valid = await verifyPassword(password, user.password)
+
+    if (!valid) {
+      return res.status(401).json({ error: 'Invalid credentials' })
+    }
+
+    // Generate token
+    const token = await generateToken({ userId: user.id })
+
+    return res.json({
+      user: { id: user.id, name: user.name, email: user.email },
+      token
+    })
+  }
+}`}
+          </CodeBlock>
+        </Card>
+
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Auth Middleware</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Protect routes by requiring a valid JWT token.
+          </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' })
+  }
+
+  try {
+    const token = header.slice(7)
+    const { userId } = await verifyToken(token)
+
+    req.user = await (await db.table('users')).find(userId)
+
+    if (!req.user) {
+      return res.status(401).json({ error: 'Unauthorized' })
+    }
+
+    next()
+  } catch {
+    return res.status(401).json({ error: 'Invalid token' })
+  }
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="Using auth middleware in routes">
+{`import { auth } from '../middleware/auth.js'
+
+export default [
+  // Public route
+  { method: 'GET', path: '/api/posts', handler: PostController.index },
+
+  // Protected route - requires authentication
+  { method: 'POST', path: '/api/posts', handler: PostController.store, middleware: [auth] },
+]`}
+          </CodeBlock>
+        </Card>
+      </div>
+    </div>
+  )
+}

package/create-basicben-app/template/src/client/pages/Database.jsx

@@ -0,0 +1,426 @@
+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 Database() {
+  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="Database"
+        subtitle="Adapters, migrations, seeding, and queries"
+      />
+
+      <div className="space-y-6">
+        {/* Database Adapters */}
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Database Adapters</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            BasicBen supports multiple databases. Configure your adapter in <code>basicben.config.js</code>.
+          </p>
+
+          <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3 mb-4">
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">SQLite</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Local file database (default)</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">PostgreSQL</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Traditional Postgres</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">Turso</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Edge SQLite (libSQL)</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">PlanetScale</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Serverless MySQL</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <div className="font-semibold text-sm">Neon</div>
+              <p className={`text-xs mt-1 ${t.muted}`}>Serverless Postgres</p>
+            </div>
+          </div>
+
+          <CodeBlock title="basicben.config.js - SQLite (default)">
+{`export default {
+  db: {
+    driver: 'sqlite',
+    url: './database.sqlite'
+  }
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="basicben.config.js - Turso">
+{`export default {
+  db: {
+    driver: 'turso',
+    url: process.env.TURSO_URL,
+    authToken: process.env.TURSO_AUTH_TOKEN
+  }
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="basicben.config.js - PlanetScale">
+{`export default {
+  db: {
+    driver: 'planetscale',
+    url: process.env.DATABASE_URL
+  }
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="basicben.config.js - Neon">
+{`export default {
+  db: {
+    driver: 'neon',
+    url: process.env.DATABASE_URL
+  }
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="Install the driver you need">
+{`# SQLite (default)
+npm install better-sqlite3
+
+# PostgreSQL
+npm install pg
+
+# Turso
+npm install @libsql/client
+
+# PlanetScale
+npm install @planetscale/database
+
+# Neon
+npm install @neondatabase/serverless`}
+          </CodeBlock>
+        </Card>
+
+        {/* Migrations */}
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Migrations</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Migrations let you version control your database schema. Each migration has an <code>up</code> function to apply changes and a <code>down</code> function to reverse them.
+          </p>
+
+          <CodeBlock title="Generate a migration">
+{`npx basicben make:migration create_posts`}
+          </CodeBlock>
+
+          <CodeBlock title="migrations/001_create_posts.js">
+{`export const up = (db) => {
+  db.exec(\`
+    CREATE TABLE posts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      user_id INTEGER NOT NULL,
+      title TEXT NOT NULL,
+      content TEXT,
+      published INTEGER DEFAULT 0,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (user_id) REFERENCES users(id)
+    )
+  \`)
+}
+
+export const down = (db) => {
+  db.exec('DROP TABLE posts')
+}`}
+          </CodeBlock>
+
+          <div className="mt-4 grid gap-3 sm:grid-cols-2">
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben migrate</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Run pending migrations</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben migrate:rollback</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Undo last batch</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben migrate:fresh</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Drop all & re-run</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben migrate:status</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Show migration status</p>
+            </div>
+          </div>
+        </Card>
+
+        {/* Seeding */}
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Seeding</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Seeds populate your database with initial or test data. Create seed files in the <code>seeds/</code> directory. Seeds run in alphabetical order.
+          </p>
+
+          <CodeBlock title="Generate a seed file">
+{`npx basicben make:seed users
+# Creates: seeds/users.js`}
+          </CodeBlock>
+
+          <CodeBlock title="seeds/01_users.js">
+{`import { db } from 'basicben'
+import { hashPassword } from 'basicben/auth'
+
+export async function seed() {
+  const password = await hashPassword('password123')
+
+  await (await db.table('users')).insert({
+    name: 'Admin User',
+    email: 'admin@example.com',
+    password
+  })
+
+  await (await db.table('users')).insert({
+    name: 'Test User',
+    email: 'test@example.com',
+    password
+  })
+
+  console.log('Seeded 2 users')
+}`}
+          </CodeBlock>
+
+          <CodeBlock title="seeds/02_posts.js">
+{`import { db } from 'basicben'
+
+export async function seed() {
+  const user = await (await db.table('users')).first()
+
+  await (await db.table('posts')).insert({
+    user_id: user.id,
+    title: 'Welcome to BasicBen',
+    content: 'Your first blog post!',
+    published: 1
+  })
+
+  console.log('Seeded posts')
+}`}
+          </CodeBlock>
+
+          <div className="mt-4 grid gap-3 sm:grid-cols-2">
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben seed</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Run all seeds</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben seed users</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Run specific seed</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben make:seed</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Generate seed file</p>
+            </div>
+            <div className={`rounded-lg p-3 ${t.card} border ${t.border}`}>
+              <code className="text-sm font-semibold">npx basicben db:seed</code>
+              <p className={`text-xs mt-1 ${t.muted}`}>Alias for seed</p>
+            </div>
+          </div>
+        </Card>
+
+        {/* Query Builder */}
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Query Builder</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            The query builder provides a fluent API for database queries with built-in SQL injection protection.
+          </p>
+
+          <CodeBlock title="Basic queries">
+{`import { db } from 'basicben'
+
+// Get all users
+const users = await (await db.table('users')).get()
+
+// Find by ID
+const user = await (await db.table('users')).find(1)
+
+// Filter with where
+const admins = await (await db.table('users'))
+  .where('is_admin', true)
+  .get()
+
+// Chain multiple conditions
+const results = await (await db.table('posts'))
+  .where('published', true)
+  .where('user_id', userId)
+  .orderBy('created_at', 'DESC')
+  .limit(10)
+  .get()`}
+          </CodeBlock>
+
+          <CodeBlock title="Insert & Update">
+{`// Insert a record
+const result = await (await db.table('posts'))
+  .insert({
+    title: 'My Post',
+    content: 'Hello world',
+    user_id: 1
+  })
+
+console.log(result.lastInsertRowid) // New ID
+
+// Update records
+await (await db.table('posts'))
+  .where('id', postId)
+  .update({ title: 'Updated Title' })
+
+// Delete records
+await (await db.table('posts'))
+  .where('id', postId)
+  .delete()`}
+          </CodeBlock>
+
+          <CodeBlock title="Aggregates & Pagination">
+{`// Count records
+const count = await (await db.table('posts'))
+  .where('published', true)
+  .count()
+
+// Check existence
+const exists = await (await db.table('users'))
+  .where('email', 'test@example.com')
+  .exists()
+
+// Paginate results
+const page = await (await db.table('posts'))
+  .orderBy('created_at', 'DESC')
+  .paginate(1, 15)
+
+// Returns: { data, total, page, perPage, totalPages }`}
+          </CodeBlock>
+        </Card>
+
+        {/* Mass Assignment Protection */}
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Mass Assignment Protection</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Prevent users from setting fields they shouldn't (like <code>is_admin</code>) by using <code>only()</code> or <code>except()</code>.
+          </p>
+
+          <CodeBlock title="Whitelist with only()">
+{`// Only allow these fields to be set
+await (await db.table('users'))
+  .only('name', 'email', 'bio')
+  .insert(req.body)
+
+// Extra fields in req.body are ignored
+// { name: 'Bob', email: 'bob@test.com', is_admin: true }
+// is_admin is silently dropped`}
+          </CodeBlock>
+
+          <CodeBlock title="Blacklist with except()">
+{`// Block specific fields
+await (await db.table('users'))
+  .except('id', 'is_admin', 'created_at')
+  .where('id', userId)
+  .update(req.body)`}
+          </CodeBlock>
+
+          <CodeBlock title="In your models">
+{`// src/models/User.js
+export const User = {
+  fillable: ['name', 'email', 'bio'],
+
+  create: async (data) => {
+    return (await db.table('users'))
+      .only(...User.fillable)
+      .insert(data)
+  },
+
+  update: async (id, data) => {
+    return (await db.table('users'))
+      .only(...User.fillable)
+      .where('id', id)
+      .update(data)
+  }
+}`}
+          </CodeBlock>
+        </Card>
+
+        {/* Database Validation */}
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Database Validation</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            Validate data against your database with <code>unique</code> and <code>exists</code> rules.
+          </p>
+
+          <CodeBlock title="Unique validation">
+{`import { validate, rules } from 'basicben/validation'
+
+// Check email is unique in users table
+const result = await validate(req.body, {
+  email: [rules.required, rules.email, rules.unique('users')]
+})
+
+// With custom column name
+slug: [rules.unique('categories', 'slug')]
+
+// Exclude current record (for updates)
+email: [rules.unique('users', 'email', userId)]`}
+          </CodeBlock>
+
+          <CodeBlock title="Exists validation">
+{`// Check foreign key exists
+const result = await validate(req.body, {
+  user_id: [rules.required, rules.exists('users')],
+  category_id: [rules.required, rules.exists('categories')]
+})
+
+// With custom column
+category: [rules.exists('categories', 'slug')]`}
+          </CodeBlock>
+        </Card>
+
+        {/* Raw Queries */}
+        <Card>
+          <h2 className="text-lg font-semibold mb-2">Raw Queries</h2>
+          <p className={`text-sm ${t.muted} mb-4`}>
+            For complex queries, you can use raw SQL with parameterized queries.
+          </p>
+
+          <CodeBlock title="Using db directly">
+{`import { db } from 'basicben'
+
+// Parameterized queries (safe from SQL injection)
+const posts = await db.all(
+  'SELECT * FROM posts WHERE user_id = ? AND published = ?',
+  [userId, true]
+)
+
+// Single row
+const user = await db.get(
+  'SELECT * FROM users WHERE email = ?',
+  [email]
+)
+
+// Insert/Update/Delete
+const result = await db.run(
+  'INSERT INTO posts (title, user_id) VALUES (?, ?)',
+  [title, userId]
+)
+
+// Transactions
+await db.transaction(async (tx) => {
+  await tx.run('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, fromId])
+  await tx.run('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, toId])
+})`}
+          </CodeBlock>
+        </Card>
+      </div>
+    </div>
+  )
+}

package/create-basicben-app/template/src/client/pages/Feed.jsx

@@ -0,0 +1,34 @@
+import { useState, useEffect } from 'react'
+import { useNavigate } from '@basicbenframework/core/client'
+import { PageHeader } from '../components/PageHeader'
+import { PostCard } from '../components/PostCard'
+import { Loading } from '../components/Loading'
+import { Empty } from '../components/Empty'
+import { api } from '../../helpers/api'
+
+export function Feed() {
+  const navigate = useNavigate()
+  const [posts, setPosts] = useState([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    api('/api/feed').then(data => setPosts(data.posts)).finally(() => setLoading(false))
+  }, [])
+
+  if (loading) return <Loading />
+
+  return (
+    <div>
+      <PageHeader title="Feed" />
+      {posts.length === 0 ? (
+        <Empty>No posts yet</Empty>
+      ) : (
+        <div className="space-y-4">
+          {posts.map(post => (
+            <PostCard key={post.id} post={post} onClick={() => navigate(`/feed/${post.id}`)} showAuthor />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}