@microsoft/rayfin-core package
Classes
| BaseExpression |
Base class for policy expressions, providing the |
| ClaimRef |
A reference to a claim on the authenticated user's token (for example, |
| ComparisonExpression |
A comparison between two operands (for example, |
| FieldRef |
A reference to a field on the target item (for example, |
| LogicalExpression |
A logical combination of two expressions (for example, |
| StorageObject |
Declaration-only base class exposing the intrinsic A storage policy may compare a claim to an intrinsic field, e.g.
These properties are Extending this class is the ergonomic option, but not required: you may
instead declare only the intrinsic you reference as an undecorated property
(e.g. Example
|
| User |
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. |
Interfaces
| FailureResult |
The result interface if validation fails. |
| Issue |
The issue interface of the failure output. |
| Options | |
| PathSegment |
The path segment interface of the issue. |
| Props |
The Standard Schema properties interface. |
| SuccessResult |
The result interface if validation succeeds. |
| Types |
The Standard types interface. |
| BaseFieldOptions |
Base field options that are common across all field types. |
| BlobFolderOptions |
Options passed to the Carries folder-level configuration that the Rayfin control plane uses when authorizing requests and minting OneLake SAS URLs. |
| BooleanConstraints |
Constraints for a boolean field ( |
| BooleanFieldOptions |
Boolean field options for true/false values. |
| CheckBranch |
A boolean combinator node with two or more operands. |
| CheckLeaf |
A leaf comparison node: |
| ComplexAction |
A permission entry that pairs an action with optional field visibility and policy. |
| CustomKeyRelationshipFieldOptions |
Relationship options that additionally allow explicit foreign-key columns. Offered only when the relationship target declares its own primary key. |
| DatabasePolicy |
A row-level security policy expressed as a database predicate. |
| DateConstraints |
Constraints for a date field ( |
| DateFieldOptions |
Date field options for temporal values. |
| DecimalFieldOptions |
Decimal field options for precise numeric values. |
| EntityClass |
Constructor type for a class decorated with |
| EntityInstance |
An instance of a decorated entity class. |
| EntityMetadata |
Metadata describing a decorated entity: its name, fields, permissions, and roles. |
| EnumConstraints |
Constraints for an enum field ( |
| FieldMetadata |
Metadata describing a single entity field, captured by field decorators. |
| FieldPermissions |
Field-level visibility for a role, restricting which fields the role can access. |
| IEntity |
Structural contract for all entity classes decorated with @entity(). Entities must either omit The property name |
| IntFieldOptions |
Integer field options for whole number fields. |
| NumberConstraints |
Constraints for a numeric-format field ( |
| PermissionConfig |
A map of role name to the permissions granted to that role. |
| PolicyExpression |
A composable policy expression that serializes to a DAB policy predicate. |
| PolicyOptions |
Options for declaring a typed row-level security policy. |
| RayfinBaseClaims |
The always-present base claims minted for every authenticated user. These mirror the historical fixed claim set and are always available on
|
| RayfinCustomClaims |
Augmentation target for an app's custom auth claims. Codegen declaration-merges the return type of the app's |
| RayfinStandardSchema |
A Standard Schema validator with a convenience
|
| RelationshipConstraints |
Constraints for a relationship field ( Relationship fields are not deeply validated by |
| RelationshipFieldOptions |
Options common to every entity relationship. |
| RoleDeclaration |
A fully-resolved role declaration stored in entity metadata. |
| RoleDeclarationOptions |
Options passed to the |
| ScalarMapping |
Maps Rayfin scalar keys to their corresponding TypeScript types. |
| SetFieldOptions |
Options for the set field decorator, which constrains a string field to a fixed set of allowed values. |
| StandardSchemaV1 |
The Standard Schema interface. |
| StoragePolicy |
A row-level security policy applied to storage (blob) access. |
| StringConstraints |
Constraints for a string-format field ( |
| TextFieldOptions |
Text field options for string fields. |
| UUIDFieldOptions |
UUID field options for unique identifier fields. |
Type Aliases
| InferInput |
Infers the input type of a Standard. |
| InferOutput |
Infers the output type of a Standard. |
| Result |
The result interface of the validate function. |
| ActionPolicy |
A row-level security policy, either a DatabasePolicy or a StoragePolicy. |
| AllClaims |
All claims available on the authenticated user's token: the always-present RayfinBaseClaims plus any app-declared claims merged into RayfinCustomClaims. |
| ByteSize |
A human-readable byte size accepted by |
| CheckLiteral |
A literal RHS value supported by the JSON DSL. |
| CheckNode |
A node in the JSON DSL check tree. |
| CheckRef |
A reference to a JWT claim or a typed item field, as it appears in the JSON DSL. |
| ClaimName |
The names of claims available on the authenticated user's token. Base claims ( |
| ClaimsDsl |
The DSL for referencing the authenticated user's claims in a policy expression. One ClaimRef per claim name. The base claims ( |
| ClientClaims |
Claims as the client SDK's Tokens carry every app-defined claim as a string, and the client does not
have the claims contract to convert them, so each custom claim is typed as
|
| ComparisonOperator |
Supported comparison operators in policy expressions. |
| DefaultFieldType |
Resolves the type permitted for a field's |
| EntityBase |
Base structural type for an entity used as a relationship target. |
| EnumFieldType |
Narrows a FieldType to its enum form (an array of string literals),
or |
| EnumValueType |
Resolves an enum field type to the union of its allowed member values. |
| FieldConstraints |
Discriminated union of all constraint shapes returned by getFieldConstraints. |
| FieldType |
Any value a field's type parameter may take: a scalar, an enum (array of string literals), or a related entity. |
| FromEntityClass |
Extracts the entity instance type from an EntityClass. |
| ItemProxy |
A typed proxy over the target type's fields, exposing each field as a
FieldRef for use in policy expressions. |
| LogicalOperator |
Supported logical operators in policy expressions. |
| MimeGlob |
A MIME glob for |
| Operand |
A value that can appear on either side of a comparison: an expression,
primitive, |
| PermissionAction |
A permission entry: either a bare SimpleAction or a ComplexAction with field visibility and policy. |
| PrimaryKeyField |
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 |
| RelationFieldType |
Narrows a FieldType to the entity class it relates to, or |
| Scalar |
Resolves a scalar key (such as |
| ScalarFieldType |
Narrows a FieldType to its scalar form, or |
| ScalarTypes |
Union of all scalar key identifiers (the keys of ScalarMapping). |
| ScalarValueType |
Resolves a scalar field type to its runtime value type (for example, the
|
| Scalars |
Union of all canonical scalar type names supported by Rayfin fields. |
| SimpleAction |
The set of actions that a role can be granted on an entity.
|
Enums
| FieldFormat |
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. When adding a format here, also add the matching category to |
| RelationshipTypes |
The set of supported relationship cardinalities. |
Functions
| anonymous<TEntity>(Simple |
Shorthand decorator for the anonymous role. Equivalent to Example
|
| authenticated<TEntity>(Simple |
Shorthand decorator for authenticated role. Equivalent to Example
|
| blob(string | Blob |
Storage folder decorator for blob storage management. Marks a class as representing a storage folder configuration.
The decorator accepts either a folder name string or a
BlobFolderOptions object. Permissions are inferred from sibling
Example
|
| boolean(Boolean |
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 Example
|
| create |
Creates an ItemProxy that resolves any accessed property to a FieldRef. |
| date(Date |
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 Example
|
| decimal(Decimal |
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 Fields are required by default. Use Example
|
| email(Text |
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 Example
|
| entity(string) | Marker decorator to indicate this class should be analyzed as a DAB entity. Entity settings inferred from class name and conventions:
Example
|
| field |
Translate a raw |
| get |
Look up the validation constraints declared by a decorator on a single
entity field. Returns Useful for UI code that needs to render constraint hints (e.g., a
|
| get |
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 |
| int(Int |
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 Example
|
| many<U>(() => U, Custom |
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
|
| many<U>(() => U, Data |
Declares a to-many (one-to-many) relationship to a data-path entity. Custom foreign-key columns ( Example
|
| one<U>(() => U, Custom |
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., Example
|
| one<U>(() => U, Data |
Declares a to-one (many-to-one) relationship to a data-path entity. The generated foreign key references the target's primary key; custom
foreign-key columns ( Example
|
| role<TEntity>("authenticated" | "anonymous", Simple |
Class-level role decorator. Declares permissions for a built-in role ( Example
|
| serialize |
Serialize a PolicyExpression tree built by the policy DSL into the
JSON-AST shape consumed by the storage service. This is the wire format
emitted into The expression tree is the same object returned by a policy lambda — there
is no re-parsing of the |
| set<T>(T) | 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
|
| set<T>(Set |
Set field decorator for constrained string values (options-only overload). Pass an options object whose Example
|
| set<T>(Omit<Set |
Set field decorator for constrained string values (options + positional values overload). Pass an options object (without Example
|
| text(Text |
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 Example
|
| to |
Build a Standard Schema validator for an
entity class declared with the Rayfin decorators ( The returned object implements the The primary key field ( Example
|
| uuid(UUIDField |
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 Example
|
Variables
| Content |
Common content types for |
| Rayfin |
|
| Rayfin |
|
| System |
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. |
| bytes | Bytes, unchanged. |
| claims | The root claims DSL used inside policy callbacks (for example, Backed by a |
| gb | Gibibytes → bytes. |
| item | A generic, untyped item proxy for convenience where a typed entity is not available. |
| kb | Kibibytes → bytes. |
| mb | Mebibytes → bytes. |
Function Details
anonymous<TEntity>(SimpleAction | SimpleAction[], RoleDeclarationOptions<TEntity>)
Shorthand decorator for the anonymous role.
Equivalent to @role('anonymous', actions, options).
Anonymous roles grant public access without an authenticated user session.
The host decides whether to accept anonymous permissions. On Microsoft Fabric,
a tenant administrator must turn on "Enable anonymous data access for Fabric Apps (Preview)"
for the app owner, or applying the schema fails with HTTP 403.
Example
import { entity, anonymous, authenticated, uuid, text } from '@microsoft/rayfin-core';
@entity()
@anonymous('read') // Anonymous users can read
@authenticated('*') // Authenticated users can do everything
export class PublicPost {
@uuid() id!: string;
@text() title!: string;
}
function anonymous<TEntity>(actions?: SimpleAction | SimpleAction[], options?: RoleDeclarationOptions<TEntity>): (target: constructor<TEntity>, context: ClassDecoratorContext<constructor<TEntity>>) => void
Parameters
- actions
The actions this role can perform (default: '*' for all actions)
- options
-
RoleDeclarationOptions<TEntity>
Optional policy and field visibility configuration
Returns
(target: constructor<TEntity>, context: ClassDecoratorContext<constructor<TEntity>>) => void
authenticated<TEntity>(SimpleAction | SimpleAction[], RoleDeclarationOptions<TEntity>)
Shorthand decorator for authenticated role.
Equivalent to @role('authenticated', actions, options).
Authenticated roles require a valid user session.
Example
@entity()
@authenticated('*', {
policy: (claims, item) => claims.sub.eq(item.user_id),
})
export class Todo {
@uuid()
id!: string;
@text()
user_id!: string;
}
function authenticated<TEntity>(actions?: SimpleAction | SimpleAction[], options?: RoleDeclarationOptions<TEntity>): (target: constructor<TEntity>, context: ClassDecoratorContext<constructor<TEntity>>) => void
Parameters
- actions
The actions this role can perform (default: '*' for all actions)
- options
-
RoleDeclarationOptions<TEntity>
Optional policy and field visibility configuration
Returns
(target: constructor<TEntity>, context: ClassDecoratorContext<constructor<TEntity>>) => void
blob(string | BlobFolderOptions)
Storage folder decorator for blob storage management.
Marks a class as representing a storage folder configuration.
The decorator accepts either a folder name string or a
BlobFolderOptions object. Permissions are inferred from sibling
@role() decorators. onConflict defaults to 'error'.
Example
import { blob, role } from '@microsoft/rayfin-core';
@blob({
name: 'uploads',
onConflict: 'error',
})
@role('authenticated', '*')
export class FileModel {
@uuid()
id!: string;
@text()
fileName!: string;
}
function blob(folderNameOrOptions?: string | BlobFolderOptions): (_target: T, context: ClassDecoratorContext<T>) => void
Parameters
- folderNameOrOptions
-
string | BlobFolderOptions
Optional folder name or full options object.
Returns
(_target: T, context: ClassDecoratorContext<T>) => void
boolean(BooleanFieldOptions)
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
}
function boolean(options?: BooleanFieldOptions): (_: T, context: ClassFieldDecoratorContext<unknown, boolean | undefined>) => void
Parameters
- options
- BooleanFieldOptions
Boolean field configuration options.
Returns
(_: T, context: ClassFieldDecoratorContext<unknown, boolean | undefined>) => void
A class field decorator.
createItemProxy<T>()
date(DateFieldOptions)
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
}
function date(options?: DateFieldOptions): (_: T, context: ClassFieldDecoratorContext<unknown, Date | undefined>) => void
Parameters
- options
- DateFieldOptions
Date field configuration options.
Returns
(_: T, context: ClassFieldDecoratorContext<unknown, Date | undefined>) => void
A class field decorator.
decimal(DecimalFieldOptions)
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
}
function decimal(options?: DecimalFieldOptions): (_: T, context: ClassFieldDecoratorContext<unknown, number | undefined>) => void
Parameters
- options
- DecimalFieldOptions
Decimal field configuration options.
Returns
(_: T, context: ClassFieldDecoratorContext<unknown, number | undefined>) => void
A class field decorator.
email(TextFieldOptions)
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;
}
function email(options?: TextFieldOptions): (_: T, context: ClassFieldDecoratorContext<unknown, string | undefined>) => void
Parameters
- options
- TextFieldOptions
Email field configuration options.
Returns
(_: T, context: ClassFieldDecoratorContext<unknown, string | undefined>) => void
A class field decorator.
entity(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;
}
function entity(name?: string): (target: T, context: ClassDecoratorContext<T>) => void
Parameters
- name
-
string
Optional explicit entity name; defaults to the class name.
Returns
(target: T, context: ClassDecoratorContext<T>) => void
A class decorator that registers the entity.
fieldMetadataToConstraints(FieldMetadata<FieldType>)
Translate a raw FieldMetadata entry into a constraint object
that is convenient to consume from UI code (form labels, hints, etc.).
function fieldMetadataToConstraints(meta: FieldMetadata<FieldType>): FieldConstraints
Parameters
- meta
The field metadata entry to translate.
Returns
The constraint object describing the field.
getFieldConstraints<T, K>(EntityClass<T>, K & string)
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.
function getFieldConstraints<T, K>(entity: EntityClass<T>, field: K & string): FieldConstraints | undefined
Parameters
- entity
-
EntityClass<T>
The entity class to inspect.
- field
-
K & string
The name of the field whose constraints to retrieve.
Returns
FieldConstraints | undefined
The field's constraints, or undefined when the field does not exist.
getPrimaryKeyField()
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.
function getPrimaryKeyField(): "id"
Returns
"id"
int(IntFieldOptions)
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
}
function int(options?: IntFieldOptions): (_: T, context: ClassFieldDecoratorContext<unknown, number | undefined>) => void
Parameters
- options
- IntFieldOptions
Integer field configuration options.
Returns
(_: T, context: ClassFieldDecoratorContext<unknown, number | undefined>) => void
A class field decorator.
many<U>(() => U, CustomKeyRelationshipFieldOptions<InstanceType<U>>)
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
}
function many<U>(target: () => U, options?: CustomKeyRelationshipFieldOptions<InstanceType<U>>): ManyRelationshipDecorator<U>
Parameters
- target
-
() => U
A thunk returning the related entity class.
- options
-
CustomKeyRelationshipFieldOptions<InstanceType<U>>
Relationship field configuration options.
Returns
ManyRelationshipDecorator<U>
A class field decorator.
many<U>(() => U, DataPathRelationshipOptions)
Declares a to-many (one-to-many) relationship to a data-path entity.
Custom foreign-key columns (sourceFields / targetFields) are
connector-only and not available here.
Example
@many(() => Book) books?: Book[];
function many<U>(target: () => U, options?: DataPathRelationshipOptions): ManyRelationshipDecorator<U>
Parameters
- target
-
() => U
A thunk returning the related entity class.
- options
-
DataPathRelationshipOptions
Relationship field configuration options.
Returns
ManyRelationshipDecorator<U>
A class field decorator.
one<U>(() => U, CustomKeyRelationshipFieldOptions<InstanceType<U>>)
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
}
function one<U>(target: () => U, options?: CustomKeyRelationshipFieldOptions<InstanceType<U>>): OneRelationshipDecorator<U>
Parameters
- target
-
() => U
A thunk returning the related entity class.
- options
-
CustomKeyRelationshipFieldOptions<InstanceType<U>>
Relationship field configuration options.
Returns
OneRelationshipDecorator<U>
A class field decorator.
one<U>(() => U, DataPathRelationshipOptions)
Declares a to-one (many-to-one) relationship to a data-path entity.
The generated foreign key references the target's primary key; custom
foreign-key columns (sourceFields / targetFields) are connector-only and
not available here.
Example
@one(() => Category) category!: Category;
function one<U>(target: () => U, options?: DataPathRelationshipOptions): OneRelationshipDecorator<U>
Parameters
- target
-
() => U
A thunk returning the related entity class.
- options
-
DataPathRelationshipOptions
Relationship field configuration options.
Returns
OneRelationshipDecorator<U>
A class field decorator.
role<TEntity>("authenticated" | "anonymous", SimpleAction | SimpleAction[], RoleDeclarationOptions<TEntity>)
Class-level role decorator.
Declares permissions for a built-in role ('authenticated' or
'anonymous') with optional typed policy and field visibility.
The 'anonymous' role has a Microsoft Fabric tenant prerequisite; see anonymous.
Example
import { entity, role, uuid, text, date } from '@microsoft/rayfin-core';
@entity()
@role('authenticated', '*', {
policy: (claims, item) => claims.sub.eq(item.user_id),
exclude: ['secret'],
})
export class Todo {
@uuid() id!: string;
@text() user_id!: string;
@text() title!: string;
@text({ optional: true }) secret?: string;
@date() createdAt!: Date;
}
function role<TEntity>(roleName: "authenticated" | "anonymous", actions: SimpleAction | SimpleAction[], options?: RoleDeclarationOptions<TEntity>): (target: constructor<TEntity>, context: ClassDecoratorContext<constructor<TEntity>>) => void
Parameters
- roleName
-
"authenticated" | "anonymous"
The role name ('authenticated' or 'anonymous')
- actions
The actions this role can perform
- options
-
RoleDeclarationOptions<TEntity>
Optional policy and field visibility configuration
Returns
(target: constructor<TEntity>, context: ClassDecoratorContext<constructor<TEntity>>) => void
serializeCheckToAst(PolicyExpression)
Serialize a PolicyExpression tree built by the policy DSL into the
JSON-AST shape consumed by the storage service. This is the wire format
emitted into StorageFolderRule.check.
The expression tree is the same object returned by a policy lambda — there
is no re-parsing of the .toString() form. v1 supports comparison operators
(eq, neq) and boolean combinators (and, or) over scalar claims.*
and item.<field> references.
function serializeCheckToAst(expr: PolicyExpression): CheckNode
Parameters
- expr
- PolicyExpression
The policy expression to serialize.
Returns
The JSON DSL check node.
set<T>(T)
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
}
function set<T>(values: T): (target: unknown, context: ClassFieldDecoratorContext<unknown, T[number] | undefined>) => void
Parameters
- values
-
T
Array of allowed string values (must have at least one value)
Returns
(target: unknown, context: ClassFieldDecoratorContext<unknown, T[number] | undefined>) => void
set<T>(SetFieldOptions<T>)
Set field decorator for constrained string values (options-only overload).
Pass an options object whose enum field carries the allowed values. Use
this overload when you want to declare options (optional, default,
etc.) and the enum together in a single object.
Example
@entity()
export class Todo {
@uuid()
id!: string;
@set({ enum: ['low', 'medium', 'high'] })
priority!: 'low' | 'medium' | 'high'; // Required enum field
@set({ enum: ['pending', 'completed'], optional: true })
status?: 'pending' | 'completed'; // Optional enum field
}
function set<T>(options: SetFieldOptions<T>): (target: unknown, context: ClassFieldDecoratorContext<unknown, T[number] | undefined>) => void
Parameters
- options
Options object including the enum array of allowed values.
Returns
(target: unknown, context: ClassFieldDecoratorContext<unknown, T[number] | undefined>) => void
set<T>(Omit<SetFieldOptions<T>, "enum">, T)
Set field decorator for constrained string values (options + positional values overload).
Pass an options object (without enum) followed by positional values. Use
this overload when you want to declare options like optional alongside
the values without nesting the enum in the options object.
Example
@entity()
export class Todo {
@uuid()
id!: string;
@set({}, 'low', 'medium', 'high')
priority!: 'low' | 'medium' | 'high'; // Required enum using positional values
@set({ optional: true }, 'pending', 'completed')
status?: 'pending' | 'completed'; // Optional enum field
@set({ default: 'low' }, 'low', 'medium', 'high')
defaultPriority!: 'low' | 'medium' | 'high'; // Required enum with default
}
function set<T>(options: Omit<SetFieldOptions<T>, "enum">, values: T): (target: unknown, context: ClassFieldDecoratorContext<unknown, T[number] | undefined>) => void
Parameters
- options
-
Omit<SetFieldOptions<T>, "enum">
Options object (must omit enum; values are passed positionally).
- values
-
T
Positional allowed string values (at least one).
Returns
(target: unknown, context: ClassFieldDecoratorContext<unknown, T[number] | undefined>) => void
text(TextFieldOptions)
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
}
function text(options?: TextFieldOptions): (_: T, context: ClassFieldDecoratorContext<unknown, string | undefined>) => void
Parameters
- options
- TextFieldOptions
Text field configuration options.
Returns
(_: T, context: ClassFieldDecoratorContext<unknown, string | undefined>) => void
A class field decorator.
toStandardSchema<T, K>(EntityClass<T>, { omit?: readonly K[] })
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);
}
function toStandardSchema<T, K>(entity: EntityClass<T>, options?: { omit?: readonly K[] }): RayfinStandardSchema<Omit<T, K | ("id" & (keyof T))>>
Parameters
- entity
-
EntityClass<T>
Entity class decorated with @entity().
- options
-
{ omit?: readonly K[] }
Optional configuration.
omit: Field names to exclude from the schema (in addition toid). The validated value type is narrowed toOmit<T, K | 'id'>. Omitted fields are also rejected as unknown if they appear in the input. TheK extends keyof Tconstraint catches typos at compile time.
Returns
RayfinStandardSchema<Omit<T, K | ("id" & (keyof T))>>
uuid(UUIDFieldOptions)
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;
}
function uuid(options?: UUIDFieldOptions): (_: T, context: ClassFieldDecoratorContext<unknown, string | undefined>) => void
Parameters
- options
- UUIDFieldOptions
UUID field configuration options.
Returns
(_: T, context: ClassFieldDecoratorContext<unknown, string | undefined>) => void
A class field decorator.
Variable Details
ContentTypes
Common content types for @blob({ allowedContentTypes }). Use these for
discoverability and typo-safety; pass a raw MimeGlob string for any
type not listed here.
ContentTypes: { AnyAudio: "audio/*", AnyImage: "image/*", AnyText: "text/*", AnyVideo: "video/*", Csv: "text/csv", Gif: "image/gif", Jpeg: "image/jpeg", Json: "application/json", Pdf: "application/pdf", Png: "image/png", Svg: "image/svg+xml", Webp: "image/webp", Zip: "application/zip" }
Type
{ AnyAudio: "audio/", AnyImage: "image/", AnyText: "text/", AnyVideo: "video/", Csv: "text/csv", Gif: "image/gif", Jpeg: "image/jpeg", Json: "application/json", Pdf: "application/pdf", Png: "image/png", Svg: "image/svg+xml", Webp: "image/webp", Zip: "application/zip" }
RayfinPrimaryKey
RayfinPrimaryKey: unique symbol
Type
unique symbol
RayfinSource
RayfinSource: unique symbol
Type
unique symbol
SystemEntityNames
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.
SystemEntityNames: Set<string>
Type
Set<string>
bytes
Bytes, unchanged. bytes(1024) === 1024.
bytes: (n: number) => number
Type
(n: number) => number
claims
The root claims DSL used inside policy callbacks (for example, claims.sub.eq(...)).
Backed by a Proxy so that any accessed property resolves to a
ClaimRef. This lets app-declared custom claims (merged into
RayfinCustomClaims) work at runtime without a hardcoded key list,
while ClaimsDsl keeps property access type-safe.
claims: ClaimsDsl
Type
gb
Gibibytes → bytes. gb(1) === 1073741824.
gb: (n: number) => number
Type
(n: number) => number
item
A generic, untyped item proxy for convenience where a typed entity is not available.
item: ItemProxy<Record<string, unknown>>
Type
ItemProxy<Record<string, unknown>>
kb
Kibibytes → bytes. kb(2) === 2048.
kb: (n: number) => number
Type
(n: number) => number
mb
Mebibytes → bytes. mb(2) === 2097152.
mb: (n: number) => number
Type
(n: number) => number