# db Field Builder API

Quick reference for `@tailor-platform/sdk` field types and options.
The `db` object is imported from `@tailor-platform/sdk`.

## Available Field Types

| Method          | Description           | Example                                 |
| --------------- | --------------------- | --------------------------------------- |
| `db.uuid()`     | UUID identifier       | `db.uuid()`                             |
| `db.string()`   | Text field            | `db.string()`                           |
| `db.bool()`     | Boolean               | `db.bool()`                             |
| `db.int()`      | Integer               | `db.int()`                              |
| `db.float()`    | Floating-point number | `db.float()`                            |
| `db.decimal()`  | Decimal (precise)     | `db.decimal()`                          |
| `db.date()`     | Date only             | `db.date()`                             |
| `db.datetime()` | Date and time         | `db.datetime()`                         |
| `db.enum()`     | Enumeration           | `db.enum(["DRAFT", "ACTIVE"] as const)` |
| `db.object()`   | Nested object / JSON  | `db.object({ key: db.string() })`       |

## Making Fields Optional (Nullable)

Pass `{ optional: true }` as the **constructor argument**. There is no `.nullable()` chain method.

```typescript
// CORRECT
db.string({ optional: true });
db.uuid({ optional: true });
db.int({ optional: true });
db.enum(["A", "B"] as const, { optional: true });
db.object({ key: db.string() }, { optional: true });
```

## Storing object

```typescript
// Option 1: Structured object (preferred when shape is known)
db.object(
  {
    hireDate: db.date({ optional: true }),
    startDate: db.date({ optional: true }),
  },
  { optional: true },
).description("Key dates map");

// Option 2: Array of objects
db.object(
  {
    kind: db.string({ optional: true }),
    days: db.int({ optional: true }),
  },
  { optional: true, array: true },
).description("Schedule lines");
```

## File Attachments

Use `.files()` on the type definition to add file fields. Do not use `db.string()` to store file URLs — `.files()` provides upload/download URL management, automatic deletion when the record is deleted, and file metadata access via GraphQL.

```typescript
db.table("Invoice", {
  invoiceNumber: db.string(),
  amount: db.decimal(),
  ...db.fields.timestamps(),
}).files({
  attachment: "invoice attachment",
});
```

`.files()` accepts an object where keys are file field names and values are description strings. Each file field gets a persistent URL endpoint and permission-based access aligned with the record.

## Timestamps

Always include timestamps via the spread helper:

```typescript
...db.fields.timestamps()
```