Field types

Every property on a @entity() class needs exactly one field decorator. The decorator determines the database column type, the GraphQL scalar, and the constraints Rayfin enforces for you. This page lists every decorator, the options it accepts, and the patterns that trip people up — especially the MSSQL text length rule.

Decorator reference

Every field decorator except @blob() also accepts the common options in the next section.

Common options

These apply to @uuid(), @text(), @int(), @decimal(), @boolean(), @date(), @email(), and @set():

import { entity, authenticated, uuid, text, boolean, date } from '@microsoft/rayfin-core';

@entity()
@authenticated('*', {
  policy: (claims, item) => claims.sub.eq(item.user_id),
})
export class Todo {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @boolean({ default: false }) isCompleted!: boolean;
  @date() createdAt!: Date;
  @text({ max: 128, description: 'Owning user, set from claims.sub on create' })
  user_id!: string;
}

The nullable pattern

Fields are required by default. To make a field nullable, you must do two things together — set { optional: true } in the decorator and mark the TypeScript property with ?. Either one alone is not enough for consistent behavior between the database constraint and the generated types.

@text() title!: string;                    // required
@text({ optional: true }) notes?: string;   // nullable — both the option and `?` are present

Text length and MSSQL

There is no safe default length to omit — pick a max that fits the data (50 for a short name, 2000 for a description, and so on). If a deploy succeeds but GraphQL queries against a new or changed entity start failing, check every @text() field on that entity for a missing max first.

@decimal() precision and scale

precision is the total number of digits (before and after the decimal point); scale is the number of digits after it. They must be provided together — if you set one, set the other. Omit both to get the default, DECIMAL(18,2). Maximum precision is 28, a limit imposed by the Data API Builder runtime.

import { entity, authenticated, uuid, decimal } from '@microsoft/rayfin-core';

@entity()
@authenticated('*')
export class Product {
  @uuid() id!: string;
  @decimal() price!: number;                       // DECIMAL(18,2) by default
  @decimal({ precision: 10, scale: 4 }) weight!: number; // DECIMAL(10,4)
}

@set() string enums

@set() takes the allowed values as separate string arguments, and the TypeScript union type should match:

@set('low', 'medium', 'high') priority!: 'low' | 'medium' | 'high';

To add common options (optional, unique, default) to a set field, pass an options object as the first argument instead, followed by the allowed values:

@set({ optional: true }, 'low', 'medium', 'high') priority?: 'low' | 'medium' | 'high';

@blob() storage folders

@blob() is a class-level decorator for experimental Rayfin Storage folders. Import it from @microsoft/rayfin-core/experimental, not from the stable package root.

import { role } from '@microsoft/rayfin-core';
import {
  blob,
  ContentTypes,
  mb,
  StorageObject,
} from '@microsoft/rayfin-core/experimental';

@blob({
  name: 'profile-images',
  onConflict: 'overwrite',
  maxSize: mb(5),
  allowedContentTypes: [ContentTypes.AnyImage],
})
@role('authenticated', '*', {
  policy: (claims, item) => claims.sub.eq(item.owner_id),
})
export class ProfileImage extends StorageObject {}

StorageObject declares server-managed intrinsic fields such as owner_id, id, path, size, and etag; do not pass those through upload metadata. Add decorated fields to the class only for application metadata you will send with upload({ fields }).

Every storage folder needs at least one authenticated permission rule. Anonymous storage permissions are not supported. File upload, download, listing, and delete operations are part of @microsoft/rayfin-storage, not client.data.