@gettersethya/mira-collection 0.1.0-alpha.10

package/dist/src/collection/field.d.ts

@@ -0,0 +1,334 @@
+import type { AnyCollectionDef, EmailConstraintKind, FieldDef, IntegerConstraintKind, LiteralTextConstraintKind, NumberConstraintKind, SimpleConstraintKind, TextConstraintKind } from "./types.js";
+/** Common options shared by all field types. */
+type BaseFieldOptions = {
+    /** Alternative field name in the database (defaults to the key in the fields map). */
+    name?: string;
+    /** Whether the field is required (defaults to `true` if no default is set). */
+    required?: boolean;
+    /** Creates a unique index on this field. */
+    unique?: boolean;
+    /** Creates a non-unique index on this field. */
+    indexed?: boolean;
+    /** Default value for the field when creating a record. */
+    default?: unknown;
+};
+/**
+ * Field builder API.
+ * Every method returns a typed `FieldDef` with `.view()` for use in `ViewCollection`.
+ *
+ * @example
+ * const Posts = BaseCollection.define("posts", {
+ *   title: Field.text({ maxLength: 200 }),
+ *   body: Field.text({ required: false }),
+ *   published: Field.boolean({ default: false }),
+ *   author: Field.relation(Users)
+ * })
+ */
+export declare const Field: {
+    /**
+     * A UTF-8 text/string field with optional min/max length constraints.
+     * Stored as `TEXT` in SQLite.
+     *
+     * @param opts.required - Whether the field is required (default: true, unless `default` is set)
+     * @param opts.default - Default value for new records
+     * @param opts.unique - Create a unique index on this field
+     * @param opts.indexed - Create a non-unique index on this field
+     * @param opts.name - Alternative column name in the database
+     * @param opts.minLength - Minimum string length (validated on create and update)
+     * @param opts.maxLength - Maximum string length (validated on create and update)
+     * @param opts.error - Callback for custom validation error messages, keyed by constraint kind
+     * @returns A text-type FieldDef with `.view()` method
+     *
+     * @example
+     * Field.text({ maxLength: 500, required: true })
+     * Field.text({ minLength: 3, maxLength: 100, default: "untitled" })
+     */
+    text: <O extends BaseFieldOptions & {
+        minLength?: number;
+        maxLength?: number;
+    }>(opts?: O & {
+        error?: (kind: TextConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "text";
+    } & O & {
+        error?: (kind: TextConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "text";
+        } & O & {
+            error?: (kind: TextConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * A text field restricted to a fixed set of literal string values.
+     * Stored as `TEXT` in SQLite. The server rejects values not in the
+     * `literal` array on create and update operations.
+     *
+     * The TypeScript type narrows to the literal union for type-safe
+     * filter expressions and client SDK usage.
+     *
+     * @param opts.literal - Required: the allowed string values (automatically narrowed via `const` type parameter)
+     * @param opts.error - Callback for custom validation error messages
+     *
+     * @example
+     * Field.literalText({ literal: ["admin", "agent", "readonly"] })
+     * Field.literalText({ literal: ["draft", "published"], default: "draft" })
+     */
+    literalText: <const L extends readonly string[], O extends Omit<BaseFieldOptions, "default"> & {
+        default?: L[number];
+    }>(opts: {
+        literal: L;
+    } & O & {
+        error?: (kind: LiteralTextConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "literalText";
+        literal: L;
+        _literal: L;
+    } & O & {
+        view(): FieldDef & {
+            kind: "literalText";
+            literal: L;
+            _literal: L;
+        } & O & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * A floating-point number field with optional min/max constraints.
+     * Stored as `REAL` in SQLite.
+     *
+     * @param opts.min - Minimum allowed value (inclusive)
+     * @param opts.max - Maximum allowed value (inclusive)
+     *
+     * @example
+     * Field.number({ min: 0, max: 100 })
+     * Field.number({ required: false })
+     */
+    number: <O extends BaseFieldOptions & {
+        min?: number;
+        max?: number;
+    }>(opts?: O & {
+        error?: (kind: NumberConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "number";
+    } & O & {
+        error?: (kind: NumberConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "number";
+        } & O & {
+            error?: (kind: NumberConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * An integer field with optional min/max constraints.
+     * Stored as `INTEGER` in SQLite. Values are validated to be whole numbers.
+     *
+     * @param opts.min - Minimum allowed value (inclusive)
+     * @param opts.max - Maximum allowed value (inclusive)
+     *
+     * @example
+     * Field.integer({ min: 1, max: 5 })
+     */
+    integer: <O extends BaseFieldOptions & {
+        min?: number;
+        max?: number;
+    }>(opts?: O & {
+        error?: (kind: IntegerConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "integer";
+    } & O & {
+        error?: (kind: IntegerConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "integer";
+        } & O & {
+            error?: (kind: IntegerConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * A boolean (true/false) field.
+     * Stored as `INTEGER` (0/1) in SQLite.
+     * Typically paired with a `default` value since new records default to false.
+     *
+     * @param opts.default - Default value (recommended to always set this)
+     *
+     * @example
+     * Field.boolean({ default: false })
+     */
+    boolean: <O extends Omit<BaseFieldOptions, "default"> & {
+        default?: boolean;
+    }>(opts?: O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "boolean";
+    } & O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "boolean";
+        } & O & {
+            error?: (kind: SimpleConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * A date/time field stored as an ISO 8601 string.
+     * Stored as `TEXT` in SQLite. Values should be ISO 8601 strings.
+     * The server does not parse or transform date values — they are stored verbatim.
+     *
+     * @example
+     * Field.date({ required: true })
+     */
+    date: <O extends BaseFieldOptions>(opts?: O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "date";
+    } & O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "date";
+        } & O & {
+            error?: (kind: SimpleConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * An email address field with built-in format validation.
+     * Stored as `TEXT` in SQLite. The server validates the email format
+     * on both create and update operations.
+     *
+     * @example
+     * Field.email({ required: false })
+     */
+    email: <O extends BaseFieldOptions>(opts?: O & {
+        error?: (kind: EmailConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "email";
+    } & O & {
+        error?: (kind: EmailConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "email";
+        } & O & {
+            error?: (kind: EmailConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * A JSON field for storing arbitrary structured data.
+     * Stored as `TEXT` (JSON string) in SQLite. The server serializes/deserializes
+     * values automatically. Can be used for dynamic metadata, nested objects, arrays, etc.
+     *
+     * @example
+     * Field.json({ required: false })
+     */
+    json: <O extends BaseFieldOptions>(opts?: O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "json";
+    } & O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "json";
+        } & O & {
+            error?: (kind: SimpleConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * Auto-incrementing sequence ID (system-managed, hidden from API responses).
+     * Stored as `INTEGER` in SQLite with `AUTOINCREMENT`.
+     * This field is always present on base and auth collections and does NOT expose
+     * `.view()` — it is always a physical column.
+     *
+     * @example
+     * // seqId is automatically included in base/auth collections — typically
+     * // only used in ViewCollection where you map a query column to seqId.
+     * Field.seqId()
+     */
+    seqId: (opts?: BaseFieldOptions) => FieldDef;
+    /**
+     * A file/attachment field referencing an uploaded file.
+     * Stored as `TEXT` (filename string) in SQLite. The actual file content is
+     * stored in the file storage backend (local disk or S3).
+     *
+     * When `protected: true`, the file requires a short-lived JWT token to access.
+     * Protected files are served via the async token endpoint.
+     *
+     * @param opts.maxSize - Maximum file size in bytes (use `Bytes.*` helpers)
+     * @param opts.mimeTypes - Allowed MIME types (e.g., ["image/jpeg", "image/png"])
+     * @param opts.protected - Whether the file requires auth token to access
+     *
+     * @example
+     * Field.file({ maxSize: Bytes.fromMB(5), mimeTypes: ["image/jpeg"] })
+     * Field.file({ protected: true, maxSize: Bytes.fromMB(10) })
+     *
+     * @see Bytes — byte size helpers for maxSize
+     */
+    file: <O extends BaseFieldOptions & {
+        maxSize?: number;
+        mimeTypes?: Array<string>;
+        protected?: boolean;
+    }>(opts?: O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "file";
+    } & O & {
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    } & {
+        view(): FieldDef & {
+            kind: "file";
+        } & O & {
+            error?: (kind: SimpleConstraintKind) => string | undefined;
+        } & {
+            viewOnly: true;
+        };
+    };
+    /**
+     * A relation field referencing another collection's record.
+     * Stores the target record's field value (defaults to `"id"`).
+     * Resolves collection names at definition time — only the name string survives
+     * into the serialized JSON Schema.
+     *
+     * The `_target` phantom property carries the collection definition at compile time
+     * for type inference in `WithExpand`.
+     *
+     * @param collection - The target collection definition (AnyCollectionDef)
+     * @param opts.field - The target field to reference (defaults to `"id"`)
+     *
+     * @example
+     * Field.relation(Users)
+     * Field.relation(Users, { field: "email" })
+     *
+     * @see WithExpand — uses _target to type expanded related records
+     */
+    relation: <C extends AnyCollectionDef, O extends BaseFieldOptions>(collection: C, opts?: O & {
+        field?: (keyof C["fields"] & string) | "id" | "created" | "updated";
+        error?: (kind: SimpleConstraintKind) => string | undefined;
+    }) => FieldDef & {
+        kind: "relation";
+        _target: C;
+    } & O & {
+        view(): FieldDef & {
+            kind: "relation";
+            _target: C;
+        } & O & {
+            viewOnly: true;
+        };
+    };
+};
+export {};
+//# sourceMappingURL=field.d.ts.map

package/dist/src/collection/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/collection/field.ts"],"names":[],"mappings":"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"}

package/dist/src/collection/field.js

@@ -0,0 +1,201 @@
+// Generic over D so the caller's specific field type (kind literal, required literal, etc.) is preserved.
+// Object.assign is used (not spread) because TypeScript infers the intersection type precisely.
+function withView(def) {
+    const viewOnlyPatch = { viewOnly: true };
+    function view() {
+        return Object.assign({}, def, viewOnlyPatch);
+    }
+    return Object.assign({}, def, { view });
+}
+// Generic field builder — K is the kind literal, O is the caller's opts (preserving required: false, etc.)
+function makeField(kind, opts) {
+    const def = { _tag: "FieldDef", kind, ...opts };
+    return withView(def);
+}
+/**
+ * Field builder API.
+ * Every method returns a typed `FieldDef` with `.view()` for use in `ViewCollection`.
+ *
+ * @example
+ * const Posts = BaseCollection.define("posts", {
+ *   title: Field.text({ maxLength: 200 }),
+ *   body: Field.text({ required: false }),
+ *   published: Field.boolean({ default: false }),
+ *   author: Field.relation(Users)
+ * })
+ */
+export const Field = {
+    /**
+     * A UTF-8 text/string field with optional min/max length constraints.
+     * Stored as `TEXT` in SQLite.
+     *
+     * @param opts.required - Whether the field is required (default: true, unless `default` is set)
+     * @param opts.default - Default value for new records
+     * @param opts.unique - Create a unique index on this field
+     * @param opts.indexed - Create a non-unique index on this field
+     * @param opts.name - Alternative column name in the database
+     * @param opts.minLength - Minimum string length (validated on create and update)
+     * @param opts.maxLength - Maximum string length (validated on create and update)
+     * @param opts.error - Callback for custom validation error messages, keyed by constraint kind
+     * @returns A text-type FieldDef with `.view()` method
+     *
+     * @example
+     * Field.text({ maxLength: 500, required: true })
+     * Field.text({ minLength: 3, maxLength: 100, default: "untitled" })
+     */
+    text: (opts) => makeField("text", opts),
+    /**
+     * A text field restricted to a fixed set of literal string values.
+     * Stored as `TEXT` in SQLite. The server rejects values not in the
+     * `literal` array on create and update operations.
+     *
+     * The TypeScript type narrows to the literal union for type-safe
+     * filter expressions and client SDK usage.
+     *
+     * @param opts.literal - Required: the allowed string values (automatically narrowed via `const` type parameter)
+     * @param opts.error - Callback for custom validation error messages
+     *
+     * @example
+     * Field.literalText({ literal: ["admin", "agent", "readonly"] })
+     * Field.literalText({ literal: ["draft", "published"], default: "draft" })
+     */
+    literalText: (opts) => {
+        const { literal, ...rest } = opts;
+        const def = {
+            _tag: "FieldDef",
+            kind: "literalText",
+            literal,
+            _literal: literal,
+            ...rest
+        };
+        return withView(def);
+    },
+    /**
+     * A floating-point number field with optional min/max constraints.
+     * Stored as `REAL` in SQLite.
+     *
+     * @param opts.min - Minimum allowed value (inclusive)
+     * @param opts.max - Maximum allowed value (inclusive)
+     *
+     * @example
+     * Field.number({ min: 0, max: 100 })
+     * Field.number({ required: false })
+     */
+    number: (opts) => makeField("number", opts),
+    /**
+     * An integer field with optional min/max constraints.
+     * Stored as `INTEGER` in SQLite. Values are validated to be whole numbers.
+     *
+     * @param opts.min - Minimum allowed value (inclusive)
+     * @param opts.max - Maximum allowed value (inclusive)
+     *
+     * @example
+     * Field.integer({ min: 1, max: 5 })
+     */
+    integer: (opts) => makeField("integer", opts),
+    /**
+     * A boolean (true/false) field.
+     * Stored as `INTEGER` (0/1) in SQLite.
+     * Typically paired with a `default` value since new records default to false.
+     *
+     * @param opts.default - Default value (recommended to always set this)
+     *
+     * @example
+     * Field.boolean({ default: false })
+     */
+    boolean: (opts) => makeField("boolean", opts),
+    /**
+     * A date/time field stored as an ISO 8601 string.
+     * Stored as `TEXT` in SQLite. Values should be ISO 8601 strings.
+     * The server does not parse or transform date values — they are stored verbatim.
+     *
+     * @example
+     * Field.date({ required: true })
+     */
+    date: (opts) => makeField("date", opts),
+    /**
+     * An email address field with built-in format validation.
+     * Stored as `TEXT` in SQLite. The server validates the email format
+     * on both create and update operations.
+     *
+     * @example
+     * Field.email({ required: false })
+     */
+    email: (opts) => makeField("email", opts),
+    /**
+     * A JSON field for storing arbitrary structured data.
+     * Stored as `TEXT` (JSON string) in SQLite. The server serializes/deserializes
+     * values automatically. Can be used for dynamic metadata, nested objects, arrays, etc.
+     *
+     * @example
+     * Field.json({ required: false })
+     */
+    json: (opts) => makeField("json", opts),
+    /**
+     * Auto-incrementing sequence ID (system-managed, hidden from API responses).
+     * Stored as `INTEGER` in SQLite with `AUTOINCREMENT`.
+     * This field is always present on base and auth collections and does NOT expose
+     * `.view()` — it is always a physical column.
+     *
+     * @example
+     * // seqId is automatically included in base/auth collections — typically
+     * // only used in ViewCollection where you map a query column to seqId.
+     * Field.seqId()
+     */
+    seqId: (opts) => ({
+        _tag: "FieldDef",
+        kind: "seqId",
+        ...opts
+    }),
+    /**
+     * A file/attachment field referencing an uploaded file.
+     * Stored as `TEXT` (filename string) in SQLite. The actual file content is
+     * stored in the file storage backend (local disk or S3).
+     *
+     * When `protected: true`, the file requires a short-lived JWT token to access.
+     * Protected files are served via the async token endpoint.
+     *
+     * @param opts.maxSize - Maximum file size in bytes (use `Bytes.*` helpers)
+     * @param opts.mimeTypes - Allowed MIME types (e.g., ["image/jpeg", "image/png"])
+     * @param opts.protected - Whether the file requires auth token to access
+     *
+     * @example
+     * Field.file({ maxSize: Bytes.fromMB(5), mimeTypes: ["image/jpeg"] })
+     * Field.file({ protected: true, maxSize: Bytes.fromMB(10) })
+     *
+     * @see Bytes — byte size helpers for maxSize
+     */
+    file: (opts) => makeField("file", opts),
+    /**
+     * A relation field referencing another collection's record.
+     * Stores the target record's field value (defaults to `"id"`).
+     * Resolves collection names at definition time — only the name string survives
+     * into the serialized JSON Schema.
+     *
+     * The `_target` phantom property carries the collection definition at compile time
+     * for type inference in `WithExpand`.
+     *
+     * @param collection - The target collection definition (AnyCollectionDef)
+     * @param opts.field - The target field to reference (defaults to `"id"`)
+     *
+     * @example
+     * Field.relation(Users)
+     * Field.relation(Users, { field: "email" })
+     *
+     * @see WithExpand — uses _target to type expanded related records
+     */
+    relation: (collection, opts) => {
+        const targetField = opts?.field ?? "id";
+        const { field: _field, ...fieldOpts } = (opts ?? {});
+        const def = {
+            _tag: "FieldDef",
+            kind: "relation",
+            targetCollection: collection.name,
+            targetField,
+            _target: collection,
+            ...fieldOpts
+        };
+        return withView(def);
+    }
+};
+//# sourceMappingURL=field.js.map

package/dist/src/collection/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../../../src/collection/field.ts"],"names":[],"mappings":"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"}

package/dist/src/collection/index-builder.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A database index entry with field names and uniqueness flag.
+ * Created via `Index.on()` or `Index.unique()`.
+ */
+export interface IndexEntry<K extends string> {
+    readonly fields: Array<K>;
+    readonly unique: boolean;
+}
+/**
+ * A narrowed version of the Index builder where methods only accept field
+ * names from `K`. Used as the argument type for the `indexes` callback.
+ */
+export type IndexBuilder<K extends string> = {
+    on<F extends K>(...fields: Array<F>): IndexEntry<F>;
+    unique<F extends K>(...fields: Array<F>): IndexEntry<F>;
+};
+/**
+ * Index builder API.
+ * Pass the result to a collection config's `indexes` option.
+ *
+ * @example
+ * BaseCollection.define({
+ *   name: "posts",
+ *   fields: { slug: Field.text(), authorId: Field.text() },
+ *   indexes: [
+ *     Index.unique("slug"),
+ *     Index.on("authorId", "createdAt")
+ *   ]
+ * })
+ */
+export declare const Index: {
+    /**
+     * Create a non-unique (plain) index on one or more fields.
+     * Composite indexes are created by passing multiple field names — order matters
+     * for query performance (leftmost prefix rule).
+     *
+     * @param fields - One or more field names to include in the index
+     * @returns An IndexEntry with `unique: false`
+     *
+     * @example
+     * Index.on("authorId")              // single-field index
+     * Index.on("authorId", "createdAt") // composite index
+     */
+    on: <const K extends string>(...fields: Array<K>) => IndexEntry<K>;
+    /**
+     * Create a unique index on one or more fields.
+     * Enforces that the combination of field values is unique across all records.
+     * Composite unique indexes check uniqueness across all listed columns together.
+     *
+     * @param fields - One or more field names to include in the unique constraint
+     * @returns An IndexEntry with `unique: true`
+     *
+     * @example
+     * Index.unique("slug")             // single-field unique constraint
+     * Index.unique("teamId", "name")   // composite unique constraint
+     */
+    unique: <const K extends string>(...fields: Array<K>) => IndexEntry<K>;
+};
+//# sourceMappingURL=index-builder.d.ts.map

package/dist/src/collection/index-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-builder.d.ts","sourceRoot":"","sources":["../../../src/collection/index-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,MAAM;IAC1C,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI;IAC3C,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;IACnD,MAAM,CAAC,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;CACxD,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;;;;;;OAWG;eACQ,CAAC,SAAS,MAAM,aAAa,KAAK,CAAC,CAAC,CAAC,KAAG,UAAU,CAAC,CAAC,CAAC;IAEhE;;;;;;;;;;;OAWG;mBACY,CAAC,SAAS,MAAM,aAAa,KAAK,CAAC,CAAC,CAAC,KAAG,UAAU,CAAC,CAAC,CAAC;CACrE,CAAA"}

package/dist/src/collection/index-builder.js

@@ -0,0 +1,43 @@
+/**
+ * Index builder API.
+ * Pass the result to a collection config's `indexes` option.
+ *
+ * @example
+ * BaseCollection.define({
+ *   name: "posts",
+ *   fields: { slug: Field.text(), authorId: Field.text() },
+ *   indexes: [
+ *     Index.unique("slug"),
+ *     Index.on("authorId", "createdAt")
+ *   ]
+ * })
+ */
+export const Index = {
+    /**
+     * Create a non-unique (plain) index on one or more fields.
+     * Composite indexes are created by passing multiple field names — order matters
+     * for query performance (leftmost prefix rule).
+     *
+     * @param fields - One or more field names to include in the index
+     * @returns An IndexEntry with `unique: false`
+     *
+     * @example
+     * Index.on("authorId")              // single-field index
+     * Index.on("authorId", "createdAt") // composite index
+     */
+    on: (...fields) => ({ fields, unique: false }),
+    /**
+     * Create a unique index on one or more fields.
+     * Enforces that the combination of field values is unique across all records.
+     * Composite unique indexes check uniqueness across all listed columns together.
+     *
+     * @param fields - One or more field names to include in the unique constraint
+     * @returns An IndexEntry with `unique: true`
+     *
+     * @example
+     * Index.unique("slug")             // single-field unique constraint
+     * Index.unique("teamId", "name")   // composite unique constraint
+     */
+    unique: (...fields) => ({ fields, unique: true })
+};
+//# sourceMappingURL=index-builder.js.map

package/dist/src/collection/index-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-builder.js","sourceRoot":"","sources":["../../../src/collection/index-builder.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;;;;;;;;;OAWG;IACH,EAAE,EAAE,CAAyB,GAAG,MAAgB,EAAiB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAE/F;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,CAAyB,GAAG,MAAgB,EAAiB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CACnG,CAAA"}

package/dist/src/collection/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Collection definition system.
+ *
+ * Provides builders for defining collections (base, auth, view), their fields,
+ * indexes, and byte-size helpers. The primary entry points are:
+ *
+ * - `BaseCollection.define()` — standard CRUD collections
+ * - `AuthCollection.define()` — auth/user collections with system fields
+ * - `ViewCollection.define()` — read-only SQL view collections
+ * - `Field.*()` — field type builders
+ * - `Index.*()` — index builders
+ * - `Bytes.*` — human-readable byte size constants
+ */
+export { AuthCollection } from "./auth.js";
+export { BaseCollection } from "./base.js";
+export { Bytes } from "./bytes.js";
+export { ValidationError } from "./errors.js";
+export { Field } from "./field.js";
+export { Index } from "./index-builder.js";
+export type { AnyCollectionDef, CollectionSchema, FieldDef, FieldsMap, LiteralTextConstraintKind } from "./types.js";
+export { ViewCollection } from "./view.js";
+//# sourceMappingURL=index.d.ts.map