@microsoft/rayfin-guide 1.1.0 → 1.33.0-beta.1

package/assets/docs/cli/quickstart.md

@@ -0,0 +1,88 @@
+---
+sidebar_position: 1
+---
+
+# CLI Quickstart
+
+Use these commands to create and manage Rayfin projects.
+
+## Pre-requisites
+
+Install the [prerequisites](../getting-started/index.md#prerequisites) before continuing.
+
+## Create a new project
+
+```bash
+npm create @microsoft/rayfin@latest my-app
+```
+
+The project name is a **positional argument** — not a flag.
+Provide a valid directory name like `my-app`, or use `.` to scaffold into the current directory.
+
+- The CLI prompts for a template and database dialect interactively.
+- Use `-t, --template <name>` to skip the template prompt (run `--list-templates` to see options).
+- Expected result: `✔ Project created`.
+
+## Add Rayfin to an existing project
+
+If you already have a project and want to add Rayfin:
+
+```bash
+npm install --save-dev @microsoft/rayfin-cli
+npx rayfin init
+```
+
+This installs the CLI and runs the interactive setup to create the `rayfin/` directory with starter configuration files.
+
+## Deploy to Fabric
+
+```bash
+npx rayfin login
+npx rayfin up
+```
+
+- Sign in with your Microsoft account when prompted.
+- The CLI uses the OS keychain for token storage when available.
+- Deploys your project to Microsoft Fabric.
+- Use `npx rayfin up status` to check deployment state.
+- Expected result: a successful deployment status for your Rayfin item.
+
+For non-interactive environments, use service principal authentication instead:
+
+```bash
+npx rayfin login --service-principal --client-id <id> --client-secret <secret> --tenant <tenant-id>
+npx rayfin up
+```
+
+## Apply database schema changes
+
+```bash
+npx rayfin up db apply [--force]
+```
+
+- Run after updating decorated entities under `rayfin/data`.
+- Ensure `npx rayfin up` has completed successfully before applying.
+- Use `--force` to proceed when warned about potential data loss.
+- Expected result: `✔ Configuration applied successfully!`.
+
+## Deploy static content
+
+If `staticHosting` is enabled in `rayfin/rayfin.yml`, `npx rayfin up` automatically builds, packages, and deploys your static assets.
+
+When iterating locally with Vite, opt out of the static deploy phase with `npx rayfin up --exclude-services staticHosting`.
+This is what the scaffolded `npm run dev` script does so the backend deploys but the local Vite server keeps serving your frontend.
+
+To redeploy static content independently without running the full `rayfin up` flow:
+
+```bash
+npx rayfin up staticapp deploy
+```
+
+- Runs the configured `buildCommand`, packages the output folder into a ZIP, and uploads it.
+- Use `--skip-build` to deploy existing build output without rebuilding.
+- Expected result: `Static content deployed` with a hosting URL.
+
+## Troubleshooting
+
+- **Authentication fails (401/403)**: Rerun auth scripts and confirm `NODE_AUTH_TOKEN` is set; verify with `npm view @microsoft/rayfin-cli version`.
+- **Database apply fails**: Wait for services to report healthy, then rerun `npx rayfin up db apply`.

package/assets/docs/data/graphql.md

@@ -0,0 +1,267 @@
+---
+sidebar_position: 2
+---
+
+# Read and Write Data with the GraphQL Client
+
+Rayfin's supports GraphQL fluent client lets you run create, read, update, and delete operations with full type safety and zero handwritten queries.
+Once you have your data models defined follow the guidance below to build out the front end of your app and use the data API client to perform read, write, update, or delete data.
+
+## Instantiate a RayfinClient
+
+Use `RayfinClient` to connect your frontend or Node.js service to the Rayfin backend.
+The generic arguments keep strong typing across REST, GraphQL fluent, and raw GraphQL clients.
+
+In most applications you should create a single client instance and reuse it.
+This is commonly implemented as a small singleton module or service wrapper.
+
+```typescript
+import { RayfinClient } from '@microsoft/rayfin-client';
+import type { Note } from '../rayfin/data/Note';
+
+type AppSchema = { Note: Note };
+
+const rayfinClient = new RayfinClient<AppSchema>({
+  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY ?? '',
+});
+```
+
+## Read Data with GraphQL
+
+Rayfin's fluent client produces DAB-compliant GraphQL and returns typed entities.
+
+The GraphQL fluent client is available as `client.data.<Entity>`.
+Some older examples may show `client.data.gql.<Entity>`.
+
+### Read multiple records
+
+Here is an example to read all the records and order by a column.
+
+```typescript
+const notes = await this.rayfinClient.data.Note.select([
+  'id',
+  'title',
+  'content',
+  'contentType',
+  'isPinned',
+  'isArchived',
+  'createdAt',
+  'updatedAt',
+  'user_id',
+  'notebook_id',
+  'notebook.id',
+  'notebook.name',
+  'notebook.color',
+])
+  .orderBy({ createdAt: 'desc' })
+  .execute();
+
+// Sort pinned notes to the top
+return this.sortWithPinnedFirst(notes);
+```
+
+### Filter records
+
+Use `where` to filter results.
+
+```typescript
+const pinnedNotes = await this.rayfinClient.data.Note.select([
+  'id',
+  'title',
+  'isPinned',
+])
+  .where({ isPinned: { eq: true } })
+  .orderBy({ createdAt: 'desc' })
+  .execute();
+```
+
+### Paginate Large Lists
+
+Use cursor pagination for large lists.
+
+```typescript
+const page = await this.rayfinClient.data.Note.select([
+  'id',
+  'title',
+  'createdAt',
+])
+  .orderBy({ createdAt: 'desc' })
+  .first(25)
+  .executePaginated();
+
+const items = page.items;
+const cursor = page.endCursor;
+const hasNextPage = page.hasNextPage;
+```
+
+### Fetch a Single Record
+
+Here is an example to fetch a single record.
+
+```typescript
+const note = await rayfinClient.data.Note.findById('00000000-0000-0000-0000-000000000000');
+```
+
+## Create Records
+
+Use `create` to insert a record with full validation based on your entity definition.
+The returned value is the newly created entity.
+
+```typescript
+const noteData = {
+  title: 'My first note',
+  content: 'test note',
+  isPinned: false,
+  isArchived: false,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+const newNote = await this.rayfinClient.data.Note.create(noteData);
+```
+
+### Creating Records with Relationships
+
+When creating entities that have relationships (defined with `@one()`), you can pass either the full related object or just an object with the primary key.
+
+**Option 1: Pass the full object**
+
+```typescript
+// If you already have the full Notebook object
+const notebook = await rayfinClient.data.Notebook.findFirst({ name: { eq: 'Work' } });
+
+const note = await rayfinClient.data.Note.create({
+  title: 'Meeting notes',
+  content: 'Discussion points...',
+  isPinned: false,
+  isArchived: false,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  notebook: notebook,  // Full object
+});
+```
+
+**Option 2: Pass an object with just the ID**
+
+```typescript
+// If you only have the notebook ID (avoids extra fetch)
+const note = await rayfinClient.data.Note.create({
+  title: 'Meeting notes',
+  content: 'Discussion points...',
+  isPinned: false,
+  isArchived: false,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  notebook: { id: 'notebook-id' },  // Just the primary key
+});
+```
+
+Both forms produce the same GraphQL mutation.
+The second form is useful when you already know the related entity's ID and don't need to fetch the full object.
+
+## Update Records
+
+Use `update` to patch records by filter.
+
+```typescript
+const noteUpdates = {
+  ...updates,
+  updatedAt: new Date(),
+};
+
+await this.rayfinClient.data.Note.update({ id }, noteUpdates);
+```
+
+### Updating Records with Relationships
+
+When updating a relationship field (defined with `@one()`), you can pass either the full related object or just an object with the primary key — the same options available when creating.
+
+```typescript
+// Move a note to a different notebook by passing just the ID
+await rayfinClient.data.Note.update(
+  { id: '00000000-0000-0000-0000-000000000000' },
+  { notebook: { id: 'new-notebook-id' } },
+);
+```
+
+The client converts the relationship object to a foreign key field (`notebook_id`) in the generated GraphQL mutation.
+
+## Delete Records
+
+Use `delete` to remove records that match a filter.
+The method resolves when the backend confirms deletion.
+
+```typescript
+await this.rayfinClient.data.Note.delete({ id });
+```
+
+## Limitations and Workarounds
+
+- `count()` is not implemented today; select the identifiers you need and use `results.length` or a custom aggregate.
+- `totalCount` appears on the `PagedResult` type but DAB does not populate it in paginated queries.
+
+## Seed Data Scripts
+
+Use `RayfinClient` in a Node.js script to populate data for development and testing.
+Read the base URL and publishable key from your project's `.env` file — never hardcode them.
+
+```typescript
+import { readFileSync } from 'fs';
+import { RayfinClient } from '@microsoft/rayfin-client';
+import type { AppSchema } from '../rayfin/data/schema';
+
+// Read connection details from .env (generated by rayfin up)
+function loadEnv(): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const line of readFileSync('.env', 'utf-8').split('\n')) {
+    const match = line.match(/^([^#=]+)=(.+)$/);
+    if (match) vars[match[1].trim()] = match[2].trim();
+  }
+  return vars;
+}
+
+const env = loadEnv();
+const client = new RayfinClient<AppSchema>({
+  baseUrl: env['VITE_RAYFIN_API_URL'],
+  publishableKey: env['VITE_RAYFIN_PUBLISHABLE_KEY'],
+  authStorage: false, // Required — Node.js has no localStorage
+});
+
+async function seed() {
+  // Sign up and sign in (email/password works for local dev only)
+  try {
+    await client.auth.signUp({ email: 'admin@example.com', password: 'Admin123!' });
+  } catch { /* user may already exist */ }
+  await client.auth.signIn({ email: 'admin@example.com', password: 'Admin123!' });
+
+  // Create entities — parent records first, then children referencing their IDs
+  const notebook = await client.data.Notebook.create({
+    name: 'Work',
+    isDefault: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  });
+
+  await client.data.Note.create({
+    title: 'First note',
+    content: 'Hello world',
+    isPinned: false,
+    isArchived: false,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    notebook: { id: notebook.id },
+  });
+}
+
+seed().catch(console.error);
+```
+
+Run with `npx tsx scripts/seed.ts`, or add `"seed": "npx tsx scripts/seed.ts"` to `package.json`.
+
+Key rules:
+
+- Set `authStorage: false` — Node.js has no `localStorage` and the client will crash without it.
+- Read `baseUrl` and `publishableKey` from `.env`, not hardcoded values — the port and key vary per project.
+- Email/password auth works for **local development seeding only**.
+  Deployed Fabric apps use Entra SSO exclusively.

package/assets/docs/data/index.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 30
+---
+
+# Data
+
+Define entities with decorators and Rayfin generates DAB-compliant schema, REST, and GraphQL endpoints.
+To get started
+
+- [Define Data Models](./overview.md)
+- [Data client for CRUD operations](./graphql.md)
+- [Data permissions](./permissions.md)
+- [Form validation](./validation.md)
+
+## Known Limitations
+
+- Date comparison queries (gt, lt, gte, lte) do not work when querying a Postgres database: [DAB issue #3094](https://github.com/Azure/data-api-builder/issues/3094)
+- Querying for the total count is unsupported: [DAB discussion #2234](https://github.com/Azure/data-api-builder/discussions/2234), [DAB issue #2369](https://github.com/Azure/data-api-builder/issues/2369)
+- Paginated querying with before is unsupported: [DAB issue #2238](https://github.com/Azure/data-api-builder/issues/2238)
+- Nested entity querying beyond the second level is currently not supported because `GraphQLQueryBuilder.buildFieldSelection()` only supports 2-level nesting (uses `split('.', 2)`).

package/assets/docs/data/overview.md

@@ -0,0 +1,270 @@
+---
+sidebar_position: 1
+---
+
+# Configure Rayfin Data Models
+
+In this guide, you will learn how to set up your data schema and define your data models.
+Each data model is defined with `@entity()` decorator.
+You can secure your API with authorization rules using `@role()` (or the `@anonymous()` and `@authenticated()` shorthands).
+
+## Tables as Entity
+
+Add `@entity()` decorator to define your model.
+Import the types you need from `rayfin-core`.
+
+**Example**
+
+```typescript
+import { entity, authenticated, uuid, text, date, many, boolean } from '@microsoft/rayfin-core';
+
+@entity()
+@authenticated('*', {
+  policy: (claims, item) => claims.sub.eq(item.user_id),
+})
+export class Notebook {
+  @uuid() id!: string;
+  @text() name!: string;
+  @text({ optional: true }) description?: string;
+  @text({ optional: true }) color?: string;
+  @boolean() isDefault!: boolean;
+  @date() createdAt!: Date;
+  @date() updatedAt!: Date;
+  @many(() => Note) notes?: Note[];
+  @text() user_id!: string;
+}
+```
+
+- Every entity has an `id` field typed as `string` that serves as the UUID primary key.
+If you do not declare `id` explicitly, Rayfin adds it to your schema automatically.
+The `id` is optional when creating items — the server generates one if omitted.
+- Policies can reference identifiers in JWT claims via the typed DSL.
+Only `sub`, `email`, and `role` are supported claims.
+
+## Entity primary key
+
+Every Rayfin entity uses a UUID `string` field named `id` as its primary key.
+If you do not declare `id` in your entity class, Rayfin adds it to the schema automatically.
+You do not need to mark the field with any special option.
+
+- Optionally declare `id` as `@uuid() id!: string;` if you want it visible in your TypeScript class.
+- The `id` field is **optional during create operations**.
+If you omit it, the server generates a UUID automatically.
+- You may supply your own UUID at creation time if you prefer client-generated identifiers.
+- Composite or non-`id` primary keys are not supported.
+
+```typescript
+@entity()
+export class Todo {
+  @uuid() id!: string; // UUID primary key, auto-generated when omitted
+  @text() title!: string;
+}
+```
+
+## Data types supported
+
+Developer should be able to define the types as shown below that will allow us to define the schema when applying to the database.
+
+| Decorator | Logical type | Notes |
+| --- | --- | --- |
+| `@uuid()` | UUID | Unique identifier. |
+| `@text()` | string | String fields. On MSSQL, omitting `max` produces `NVARCHAR(MAX)` columns which can cause GraphQL schema generation failures at deploy time. Always specify `max` — e.g., `@text({ max: 200 })`. |
+| `@int()` | int | Integer type. |
+| `@decimal()` | decimal | Decimal or numeric type, depending on dialect. |
+| `@boolean()` | boolean | True or false type. |
+| `@date()` | datetime | Serializes from ISO strings or `Date` objects. |
+| `@email()` | string | Text field with email validation. |
+| `@set()` | enum | Enumerated set of string literals. |
+
+## Type modifiers
+
+You can add modifiers to the your fields based on the type of the field.
+
+- `{optional: boolean}` — make the field nullable in the database.
+Fields are required (non-nullable) by default; use `{ optional: true }` to explicitly allow NULL values.
+- `{unique: boolean}` — add a unique constraint for this field.
+- `{default: value}` — default value expression for the column.
+- `{max: n}`, `{min: n}` — string length constraints (also used for numeric range constraints).
+- `{pattern: "regex"}` — string validation pattern.
+
+## Relationships and Ownership
+
+One to many and many to one are supported with Rayfin.
+Use `@one(() => Parent)` and `@many(() => Child)` to describe navigation properties without writing SQL joins.
+Many to many currently is not supported.
+
+Rayfin auto-generates relationship columns when you define navigation decorators.
+Define foreign key fields only if you need to read or set them in application code.
+When you do define them, use the `{property}_id` naming convention.
+
+**Example**
+
+```typescript
+import { entity, authenticated, text, set, date, uuid, boolean, one } from '@microsoft/rayfin-core';
+import { Notebook } from './Notebook.js';
+
+@entity()
+@authenticated('*', {
+  policy: (claims, item) => claims.sub.eq(item.user_id),
+})
+export class Note {
+  @uuid() id!: string;
+  @text() title!: string;
+  @text() content!: string;
+  @set('markdown', 'html', 'plaintext')
+  contentType!: 'markdown' | 'html' | 'plaintext';
+  @boolean() isPinned!: boolean;
+  @boolean() isArchived!: boolean;
+  @date() createdAt!: Date;
+  @date() updatedAt!: Date;
+  @uuid() notebook_id!: string;
+  @one(() => Notebook, { optional: true }) notebook?: Notebook;
+  @text() user_id!: string;
+}
+```
+
+When authoring entity files, use `.js` extensions for relative imports so the emitted ESM JavaScript resolves correctly.
+
+## Using relationships in CRUD operations
+
+After defining `@one()` and `@many()` relationships, you can create or update related entities by passing either a full object or an ID-only object.
+The ID-only shape is the recommended shorthand for most write operations.
+
+```typescript
+await client.data.Note.create({
+  title: 'Draft architecture review',
+  content: 'Outline relationship behavior',
+  notebook: { id: 'notebook-123' },
+});
+
+await client.data.Note.update(
+  { id: 'note-456' },
+  {
+    notebook: { id: 'notebook-789' },
+  }
+);
+```
+
+You can still pass a full related object when you already have it available.
+Both forms are supported and produce equivalent relationship updates.
+
+```typescript
+await client.data.Note.create({
+  title: 'Weekly summary',
+  content: 'Use full object when convenient',
+  notebook: {
+    id: 'notebook-123',
+    name: 'Work',
+    isDefault: false,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    user_id: 'user-1',
+  },
+});
+```
+
+For complete mutation examples and response behavior, see [Use GraphQL Query Builder](./graphql.md).
+
+## Schema registration
+
+`schema.ts` binds entity names to their classes so `RayfinClient` can provide GraphQL proxies.
+
+```typescript
+import type { Note } from './Note.js';
+import type { Notebook } from './Notebook.js';
+
+export type NotesAppSchema = {
+  Note: Note;
+  Notebook: Notebook;
+};
+```
+
+Add every new entity to this map and update the exported type wherever it is imported (most commonly in service factories).
+
+## Applying Model Changes
+
+Ensure the correct backend is running and ports are free before applying.
+If you switch templates or database dialects, stop or purge stale services to avoid hitting the wrong endpoint.
+
+1. Redeploy with `npx rayfin up` and wait for services to be healthy.
+2. Regenerate the schema by running `npx rayfin up db apply`.
+3. Refresh the frontend client.
+
+The regeneration step updates tables, relationships, and permissions so subsequent API calls reflect your latest decorators.
+
+## Authorization rules using `@role()`
+
+Rayfin uses class-level role decorators to generate Data API Builder (DAB) permissions.
+Use `@role()` directly, or the `@anonymous()` and `@authenticated()` shorthands.
+
+> **Anonymous data access is not currently supported on Fabric.**
+> Both `@anonymous(...)` and `@role('anonymous', …)` are accepted at compile time, but `rayfin dev` and `rayfin up`, along with any sub-command that involves creating, updating, or applying data schema, reject any DAB configuration that grants the `anonymous` role. Remove the `@anonymous(...)` decorator (or `@role('anonymous', …)`) from your entities; all access then goes through the `authenticated` role.
+>
+> The `@anonymous()` shorthand is published from the experimental subpath as a preview of the future supported syntax:
+>
+> ```typescript
+> import { anonymous } from '@microsoft/rayfin-core/experimental';
+> ```
+>
+> The `@role('anonymous', …)` form is also importable from `@microsoft/rayfin-core/experimental` and behaves identically.
+
+### Public read, authenticated write
+
+The shape below previews the future syntax for public-read access. Anonymous data access is **not currently supported on Fabric**, so applying this schema fails today; remove `@anonymous('read')` to fall back to authenticated-only access.
+
+```typescript
+import { entity, authenticated, uuid, text } from '@microsoft/rayfin-core';
+import { anonymous } from '@microsoft/rayfin-core/experimental';
+
+@entity()
+@anonymous('read')
+@authenticated(['create', 'read', 'update', 'delete'], {
+  policy: (claims, item) => claims.sub.eq(item.user_id),
+})
+export class Todo {
+  @uuid() id!: string;
+  @text() title!: string;
+  @text() user_id!: string;
+}
+```
+
+### Field visibility
+
+Use `include` or `exclude` in the role options to control which fields are visible for that role.
+
+```typescript
+import { entity, authenticated, uuid, text } from '@microsoft/rayfin-core';
+
+@entity()
+@authenticated('read', {
+  policy: (claims, item) => claims.sub.eq(item.owner_id),
+  exclude: ['secret'],
+})
+export class Document {
+  @uuid() id!: string;
+  @text() owner_id!: string;
+  @text() title!: string;
+  @text({ optional: true }) secret?: string;
+}
+```
+
+### Notes
+
+- `@role()` applies to classes.
+Field visibility is configured through role options.
+- Only the built-in roles are supported today: `anonymous` and `authenticated`.
+
+## Best practices
+
+- Include a `user_id` field when using per-user policies.
+- Start with restrictive permissions and expand as needed.
+- Use separate `@role()` entries when field visibility differs by action.
+- Prefer `@anonymous()` and `@authenticated()` shorthands for built-in roles.
+
+## Troubleshooting Checklist
+
+- Missing relationships usually mean the navigation decorator is absent or the schema was not applied; foreign keys are generated automatically unless you define them explicitly.
+- Authorization failures often trace back to mismatched claim names, so log the decoded JWT when debugging policies.
+- If the frontend still returns stale shapes, delete `rayfin/.temp/` within the sample and rerun `npx rayfin up` to force regeneration.
+
+Use these patterns as building blocks for any Rayfin-powered application and iteratively refine the model as product requirements evolve.