windsurfrules

EloquentJS — Windsurf Rules

Stack

Node.js ESM + EloquentJS ORM + PostgreSQL/MongoDB + Express/Fastify

Packages

• @eloquentjs/core — Model, QueryBuilder, Relations, Events, Casts
• @eloquentjs/validator — Validation (fluent schema + async DB rules)
• @eloquentjs/pgsql — PostgreSQL driver with pool management
• @eloquentjs/graphql — Auto GraphQL from models
• @eloquentjs/api — Auto REST CRUD routes
• @eloquentjs/realtime — WebSocket broadcasting
• @eloquentjs/cli — Scaffold and migration commands

Critical Rules

1. Always await DB calls

// Every Model method returns a Promise
const user = await User.findOrFail(id)      // ✅
const user = User.findOrFail(id)            // ❌ Promise, not User

2. Eager load relations

// ✅ One query per relation
const posts = await Post.with('user', 'tags', 'comments').get()

// ❌ N+1: one extra query per post
const posts = await Post.all()
for (const p of posts) { const u = await p.user() }

3. Declare fillable

// ✅ Required for create/update to work
class User extends Model {
  static fillable = ['name', 'email', 'password']
}

// ❌ Empty fillable = nothing gets saved
class User extends Model {}

4. Validate before write

import { v } from '@eloquentjs/validator'

const schema = v.schema({
  email: v.string().email(),
  name:  v.string().min(2),
})
const data = schema.parse(req.body)       // throws on invalid
await User.create(data)

5. Use findOrFail for required records

// ✅ Throws ModelNotFoundException → handle as 404
const user = await User.findOrFail(req.params.id)

// ❌ Need manual null check
const user = await User.find(req.params.id)
if (!user) return res.status(404).json({ error: 'Not found' })

Model Template

import { Model } from '@eloquentjs/core'

export default class ModelName extends Model {
  static table       = 'table_name'
  static fillable    = ['field1', 'field2']
  static hidden      = []
  static softDeletes = false
  static casts = {
    // field: 'boolean' | 'integer' | 'decimal:2' | 'json' | 'array' | 'date' | 'datetime'
  }

  // Relations
  // parent()   { return this.belongsTo(Parent) }
  // children() { return this.hasMany(Child) }

  // Scopes
  // static scopeName(qb) { return qb.where(...) }

  // Hooks
  // static async creating(record) { }
  // static async created(record)  { }
}