@microsoft/rayfin-core package

Base class for policy expressions, providing the and/or combinators.

A reference to a claim on the authenticated user's token (for example, claims.sub).

A comparison between two operands (for example, @claims.sub eq @item.user_id).

A reference to a field on the target item (for example, item.user_id).

A logical combination of two expressions (for example, (...) and (...)).

Built-in User entity representing the system's user table. This is a readonly entity managed by the Rayfin platform backend. Only safe fields are exposed - no passwords or sensitive data.

The Standard Schema interface.

The result interface if validation fails.

The issue interface of the failure output.

The path segment interface of the issue.

The Standard Schema properties interface.

The result interface if validation succeeds.

The Standard types interface.

Base field options that are common across all field types.

Constraints for a boolean field (@boolean).

Boolean field options for true/false values.

A permission entry that pairs an action with optional field visibility and policy.

A row-level security policy expressed as a database predicate.

Constraints for a date field (@date).

Date field options for temporal values.

Decimal field options for precise numeric values.

Constructor type for a class decorated with @entity(), carrying entity metadata.

An instance of a decorated entity class.

Metadata describing a decorated entity: its name, fields, permissions, and roles.

Constraints for an enum field (@set).

Metadata describing a single entity field, captured by field decorators.

Field-level visibility for a role, restricting which fields the role can access.

Structural contract for all entity classes decorated with @entity().

Entities must either omit id entirely (database-generated) or declare id as a string. Non-string IDs are rejected at compile time.

The property name id aligns with the PrimaryKeyField type alias, which is the single source of truth for the PK field name.

Integer field options for whole number fields.

Constraints for a numeric-format field (@int, @decimal).

A map of role name to the permissions granted to that role.

A composable policy expression that serializes to a DAB policy predicate.

Options for declaring a typed row-level security policy.

A Standard Schema validator with a convenience validate() method.

• Pass the object to any Standard Schema-compatible library (TanStack Form, Conform, tRPC v11, etc.) — they read ~standard.
• Call .validate(value) directly from your own form code.

Constraints for a relationship field (@one, @many).

Relationship fields are not deeply validated by toStandardSchema — they are accepted as-is so that callers can attach related entities to form payloads without re-walking the graph.

Relationship field options for entity relationships.

A fully-resolved role declaration stored in entity metadata.

Options passed to the @role() and @authenticated() decorators.

Maps Rayfin scalar keys to their corresponding TypeScript types.

Options for the set field decorator, which constrains a string field to a fixed set of allowed values.

A row-level security policy applied to storage (blob) access.

Constraints for a string-format field (@text, @uuid, @email).

Text field options for string fields.

UUID field options for unique identifier fields.

Infers the input type of a Standard.

Infers the output type of a Standard.

The result interface of the validate function.

A row-level security policy, either a DatabasePolicy or a StoragePolicy.

The names of claims available on the authenticated user's token.

• sub — the user's unique identifier.
• email — the user's email address.
• role — the user's role.

The DSL for referencing the authenticated user's claims in a policy expression.

Supported comparison operators in policy expressions.

Resolves the type permitted for a field's default value, derived from whether the field is a scalar or an enum.

Base structural type for an entity used as a relationship target.

Narrows a FieldType to its enum form (an array of string literals), or never if it is not an enum field.

Resolves an enum field type to the union of its allowed member values.

Discriminated union of all constraint shapes returned by getFieldConstraints.

Any value a field's type parameter may take: a scalar, an enum (array of string literals), or a related entity.

Extracts the entity instance type from an EntityClass.

A typed proxy over an entity's fields, exposing each field as a FieldRef for use in policy expressions.

Supported logical operators in policy expressions.

A value that can appear on either side of a comparison: an expression, primitive, Date, or null.

A permission entry: either a bare SimpleAction or a ComplexAction with field visibility and policy.

Canonical primary key field name as a string literal type.

All type-level references to the PK field name across rayfin-core and rayfin-data use this alias instead of hardcoded 'id' literals.

Narrows a FieldType to the entity class it relates to, or never if it is not a relationship field.

Resolves a scalar key (such as 'string') to the canonical scalar type name (such as 'String') used by the generated schema.

Narrows a FieldType to its scalar form, or never if it is not a scalar field.

Union of all scalar key identifiers (the keys of ScalarMapping).

Resolves a scalar field type to its runtime value type (for example, the 'string' scalar resolves to string).

Union of all canonical scalar type names supported by Rayfin fields.

The set of actions that a role can be granted on an entity.

'*' grants all actions. Used by the @role() and @authenticated() decorators.

Field format enum for decorator metadata.

Defines the set of supported field formats that decorators can use to specify the database column type and serialization format.

The set of supported relationship cardinalities.

Shorthand decorator for authenticated role.

Equivalent to @role('authenticated', actions, options). Authenticated roles require a valid user session.

Example

@entity()
@authenticated('*', {
  check: (claims, item) => claims.sub.eq(item.user_id),
})
export class Todo {
  @uuid()
  id!: string;
  @text()
  user_id!: string;
}

Storage folder decorator for blob storage management.

Marks a class as representing a storage folder configuration. Folder settings inferred from class name and optional parameter:

• Folder name: parameter value or kebab-case class name
• Permissions: inferred from @role() decorators
• Visibility: inferred from permission configuration

Example

@blob('uploads')
@role('authenticated', '*')
export class FileModel {
  @uuid()
  id!: string;

  @text()
  fileName!: string;
}

Boolean field decorator for true/false values.

Specifies a field as boolean type, mapping to database boolean types (BIT, BOOLEAN, etc. depending on dialect).

Fields are required by default. Use { optional: true } for nullable fields.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @text()
  title!: string;

  @boolean()
  isCompleted!: boolean;    // Boolean field (required by default)

  @boolean({ optional: true })
  isArchived?: boolean;     // Optional boolean field
}

Creates an ItemProxy that resolves any accessed property to a FieldRef.

Date/datetime field decorator for temporal values.

Specifies a field as date type, mapping to database datetime types (DATETIME2, TIMESTAMP, etc. depending on dialect).

Fields are required by default. Use { optional: true } for nullable fields.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @text()
  title!: string;

  @date()
  createdAt!: Date;         // Date field (required by default)

  @date({ optional: true })
  dueDate?: Date;           // Optional date field
}

Decimal field decorator for precise numeric values.

Specifies a field as decimal/numeric type, mapping to database decimal types (DECIMAL, NUMERIC, etc. depending on dialect). Useful for monetary values and precise numeric calculations.

When no precision or scale is specified, defaults to DECIMAL(18,2) on MSSQL and NUMERIC(18,2) on PostgreSQL. If either precision or scale is provided, both must be specified.

Fields are required by default. Use { optional: true } for nullable fields.

Example

@entity()
export class Product {
  @uuid()
  id!: string;

  @decimal()
  price!: number;           // DECIMAL(18,2) by default

  @decimal({ precision: 10, scale: 4 })
  weight!: number;          // DECIMAL(10,4)

  @decimal({ optional: true })
  discount?: number;        // Optional decimal field
}

Email field decorator for email addresses.

Specifies a field as email type, mapping to database string types with email format validation hints.

The regex pattern is similar to RFC 5322, but has some extra restrictions to catch common mistakes. If you need full UTF-8 support or less strict validation, use a text() field with a custom regex.

The format hint can be used for validation and UI rendering. Fields are required by default. Use { optional: true } for nullable fields.

Example

@entity()
export class User {
  @uuid()
  id!: string;

  @email({ unique: true })
  emailAddress!: string;    // Email field with unique constraint (required by default)

  @text()
  name!: string;
}

Marker decorator to indicate this class should be analyzed as a DAB entity.

Entity settings inferred from class name and conventions:

• Entity name: kebab-case class name (e.g., "Todo" → "todo")
• Source table: pluralized snake_case name (e.g., "Todo" → "todos")
• Schema: default schema for the target database dialect

Example

@entity()
export class Todo {
  @uuid()
  id!: string;
}

Translate a raw FieldMetadata entry into a constraint object that is convenient to consume from UI code (form labels, hints, etc.).

Look up the validation constraints declared by a decorator on a single entity field. Returns undefined when the field does not exist.

Useful for UI code that needs to render constraint hints (e.g., a maxLength indicator on a text input) without taking on the cost of building a full Standard Schema for the entity.

Return the canonical primary key field name at runtime.

All runtime references to the PK field name across rayfin-core and rayfin-data call this function instead of using hardcoded 'id' literals.

Integer field decorator for whole numbers.

Specifies a field as integer type, mapping to database integer types (INT, INTEGER, etc. depending on dialect).

Fields are required by default. Use { optional: true } for nullable fields.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @int()
  priority!: number;        // Integer field (required by default)

  @int({ optional: true })
  order?: number;           // Optional integer field
}

One-to-many relationship decorator.

Marks a field as a relationship to multiple entity instances (collection). Represents the inverse side of a many-to-one relationship. The target entity type should be specified as an array in the TypeScript type annotation.

Example

@entity()
export class Category {
  @uuid()
  id!: string;

  @text()
  name!: string;

  @many(() => Todo)
  todos!: Todo[];          // One-to-many: reverse side of Todo.category
}

@entity()
export class User {
  @uuid()
  id!: string;

  @many(() => Todo)
  assignedTodos!: Todo[];  // One-to-many relationship
}

One-to-one or many-to-one relationship decorator.

Marks a field as a relationship to a single entity instance. Automatically generates a foreign key column (e.g., category_id for a category field). The target entity type should be specified in the TypeScript type annotation.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @text()
  title!: string;

  @one(() => Category)
  category!: Category;     // Many-to-one: generates category_id FK

  @one(() => User)
  assignee?: User;         // Optional many-to-one relationship
}

Class-level role decorator.

Declares permissions for the built-in 'authenticated' role with optional typed policy and field visibility.

Set field decorator for constrained string values.

Specifies a field as an set (or enum-like) type with a limited set of allowed values. Maps to database string types (NVARCHAR, VARCHAR, etc.) with check constraints. The set values should match the TypeScript union type annotation.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @text()
  title!: string;

  @set('low', 'medium', 'high')
  priority!: 'low' | 'medium' | 'high';  // Enum field with check constraint
}

Set field decorator for constrained string values.

Specifies a field as an set (or enum-like) type with a limited set of allowed values. Maps to database string types (NVARCHAR, VARCHAR, etc.) with check constraints. The set values should match the TypeScript union type annotation.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @text()
  title!: string;

  @set({ enum: ['low', 'medium', 'high'] })
  priority!: 'low' | 'medium' | 'high';  // Enum field with check constraint

  @set({ enum: ['pending', 'completed'], optional: true })
  status?: 'pending' | 'completed';      // Optional enum field
}

Set field decorator for constrained string values.

Specifies a field as an set (or enum-like) type with a limited set of allowed values. Maps to database string types (NVARCHAR, VARCHAR, etc.) with check constraints. The set values should match the TypeScript union type annotation.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @text()
  title!: string;

  @set({}, 'low', 'medium', 'high')
  priority!: 'low' | 'medium' | 'high';  // Enum field with check constraint

  @set({ optional: true }, 'pending', 'completed')
  status?: 'pending' | 'completed';      // Optional enum field
}

Text field decorator for long text content.

Specifies a field as text type, mapping to database text types (NVARCHAR(MAX), TEXT, etc. depending on dialect).

Fields are required by default. Use { optional: true } for nullable fields.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;

  @text()
  title!: string;           // Required text field (default)

  @text({ optional: true })
  description?: string;     // Optional text field

  @text({ unique: true })
  slug!: string;            // Unique and required text field
}

Build a Standard Schema validator for an entity class declared with the Rayfin decorators (@entity, @text, @uuid, @int, @boolean, @set, …).

The returned object implements the ~standard contract and can be passed to any Standard Schema-compatible library. It also exposes a convenience .validate() method so form code doesn't need ['~standard'].validate().

The primary key field (id) is automatically omitted — form schemas never validate server-generated IDs. Pass additional field names via omit for other server-managed fields like timestamps.

Example

import { toStandardSchema } from '@microsoft/rayfin-core';
import { Todo } from '../rayfin/data/Todo.js';

// id is auto-omitted — only list additional fields to exclude
const todoInput = toStandardSchema(Todo, {
  omit: ['createdAt', 'updatedAt'] as const,
});

const result = todoInput.validate(formValues);
if (result.issues) {
  // show errors keyed by issue.path[0]
} else {
  await api.createTodo(result.value);
}

UUID field decorator for unique identifiers.

Specifies a field as UUID/GUID type, mapping to database UUID types (UNIQUEIDENTIFIER, UUID, etc. depending on dialect).

Fields are required by default. Use { optional: true } for nullable fields. Fields named id are automatically inferred as primary keys. Use { unique: true } for unique constraint.

Example

@entity()
export class Todo {
  @uuid()
  id!: string;              // UUID primary key (required by default)

  @uuid()
  userId!: string;          // UUID foreign key (required by default)

  @uuid({ optional: true })
  optionalId?: string;      // Optional UUID field

  @text()
  title!: string;
}

Set of system entity names that are always valid relationship targets. These entities are managed by the Rayfin platform and do not need to be included in user schema arrays.

The root claims DSL used inside policy callbacks (for example, claims.sub.eq(...)).

A generic, untyped item proxy for convenience where a typed entity is not available.