Models and fields
What you’ll learn
- What a “model” is, and why it’s the heart of a Strutvane app
- Every field type, with a plain explanation and an example
- Modifiers like
optional,uniqueandfilterable
What is a model?
Section titled “What is a model?”A model describes one kind of thing your app keeps track of: a customer, an invoice, a product. Think of it as the column headings of a spreadsheet:
| name | tier | |
|---|---|---|
| Ada Ltd | hi@ada.dev | pro |
| Bob & Co | bob@bob.co | free |
As a Strutvane model, that spreadsheet looks like this:
import { defineModel, field } from '@strutvane/framework'
export const Customer = defineModel('Customer', { name: field.string(120).searchable().sortable(), email: field.email().unique(), tier: field.enum(['free', 'pro', 'enterprise']).default('free').filterable(),})Each line is a field: a name (email) plus a type (field.email()). That one file is enough for Strutvane to create the database table, the API, the validation and the screens.
Field types
Section titled “Field types”| Type | Plain meaning | Example |
|---|---|---|
field.string(max?) |
Short text, like a name or title (255 characters unless you say otherwise) | title: field.string(200) |
field.text() |
Long text, like notes or a description | notes: field.text().optional() |
field.email() |
An email address, checked automatically | email: field.email() |
field.url() |
A web address | website: field.url().optional() |
field.uuid() |
A unique id from another system | externalId: field.uuid() |
Numbers
Section titled “Numbers”| Type | Plain meaning | Example |
|---|---|---|
field.integer() |
Whole numbers | quantity: field.integer().min(0) |
field.bigInteger() |
Very large whole numbers (sent as text, so nothing is rounded) | views: field.bigInteger() |
field.decimal(p, s) |
Exact decimals. decimal(12, 2) means up to 12 digits, 2 after the dot. Use it for money. |
amount: field.decimal(12, 2) |
field.float() |
Approximate decimals (fine for measurements, not for money) | weightKg: field.float() |
Choices and yes/no
Section titled “Choices and yes/no”| Type | Plain meaning | Example |
|---|---|---|
field.boolean() |
Yes or no | active: field.boolean().default(true) |
field.enum([...]) |
Exactly one value from a fixed list | status: field.enum(['draft', 'sent', 'paid']) |
Dates and times
Section titled “Dates and times”| Type | Plain meaning | Example |
|---|---|---|
field.date() |
A calendar date | dueDate: field.date() |
field.datetime() |
A moment in time, stored in UTC | startsAt: field.datetime() |
Links between models (relations)
Section titled “Links between models (relations)”| Type | Plain meaning | Example |
|---|---|---|
field.belongsTo('Company') |
“This contact works at one company” | company: field.belongsTo('Company') |
field.hasMany('Contact') |
“This company has many contacts” | contacts: field.hasMany('Contact') |
A belongsTo value must point to a record the caller can see, in the same tenant. Another company’s id is refused, even if it exists.
Structured data
Section titled “Structured data”| Type | Plain meaning | Example |
|---|---|---|
field.json() |
Flexible structured data | settings: field.json().optional() |
Modifiers: fine-tuning a field
Section titled “Modifiers: fine-tuning a field”Modifiers are chained after the type, like field.string().unique().searchable().
| Modifier | What it does | Example |
|---|---|---|
.optional() / .nullable() |
May be empty (fields are required by default) | notes: field.text().optional() |
.unique() |
No two records may share this value (per tenant, on tenant models) | email: field.email().unique() |
.index() |
Adds a database index, for faster lookups | code: field.string(20).index() |
.default(value) |
The value used when none is given | .default('draft') |
.min() / .max() |
Limits for numbers, or for text length | .min(0).max(100) |
.regex(pattern) |
Text must match a pattern | .regex(/^INV-\d+$/) |
.searchable() |
Included when someone types in the search box (text fields) | title: field.string().searchable() |
.filterable(...ops?) |
Can be used in filters. Pass operators to allow only those. | status: field.enum([...]).filterable() |
.sortable() |
Can be used for sorting (?sort=-amount) |
amount: field.decimal(12, 2).sortable() |
.hidden() |
Never sent out by the API | internalCode: field.string().hidden() |
.readOnly() |
Sent out, but can’t be changed through the API | invoiceNo: field.string().readOnly() |
.writeOnce() |
Can be set when creating, never changed afterwards | customer: field.belongsTo('Customer').writeOnce() |
.sensitive() |
Masked in logs and the audit history | taxId: field.string().sensitive() |
.label('…') / .help('…') |
The friendly name and hint text shown in forms | .label('Due date').help('When payment is expected') |
Model options
Section titled “Model options”The third argument switches on extra behaviour for the whole model:
export const Invoice = defineModel('Invoice', { /* fields */ }, { timestamps: true, // createdAt and updatedAt (on by default) softDeletes: true, // "delete" moves records to a bin you can restore from tenant: true, // each customer company sees only its own invoices audit: true, // records who changed what, and when title: 'number', // which field to show in pickers and breadcrumbs})You can also set table (the database table name) and label / pluralLabel (the names shown in the UI). Sensible defaults are worked out from the model name.
Planned field types
Section titled “Planned field types”These are part of the design, but not built yet: phone, slug, password, richText / markdown, color, money, percent, set, time, duration, hasOne, manyToMany, address and geoPoint. Until then, use string, decimal, enum or json.