@gravito/ripple 3.1.0 → 4.0.1

package/dist/atlas/src/orm/model/concerns/HasPersistence.d.ts

@@ -0,0 +1,92 @@
+/**
+ * HasPersistence Concern
+ * @description Provides database persistence functionality including saving, deleting, and refreshing.
+ */
+export declare class HasPersistence {
+    /**
+     * Indicates if the model exists in the database.
+     * @internal
+     */
+    protected _exists: boolean;
+    /**
+     * Check if the model instance exists in the database.
+     *
+     * @returns True if the model has been persisted
+     */
+    get exists(): boolean;
+    /**
+     * Internal helper to retrieve the correct connection depending on sharding configuration
+     * @internal
+     */
+    protected _getConnection(): import('../../../types').ConnectionContract;
+    /**
+     * Save the model instance to the database (insert or update).
+     *
+     * @returns A promise that resolves to the model instance
+     *
+     * @example
+     * ```typescript
+     * await user.save()
+     * ```
+     */
+    save(): Promise<this>;
+    /**
+     * Perform an insert operation for a new model instance.
+     *
+     * @returns A promise that resolves to the model instance
+     * @internal
+     */
+    protected _performInsert(): Promise<this>;
+    /**
+     * Perform an update operation for an existing model instance.
+     *
+     * @returns A promise that resolves to the model instance
+     * @internal
+     */
+    protected _performUpdate(): Promise<this>;
+    /**
+     * Delete the model instance from the database.
+     * Supports soft deletes if configured on the model.
+     *
+     * @returns A promise that resolves to true if deleted successfully
+     *
+     * @example
+     * ```typescript
+     * await user.delete()
+     * ```
+     */
+    delete(): Promise<boolean>;
+    /**
+     * Restore a soft-deleted model instance.
+     *
+     * @returns A promise that resolves to true
+     *
+     * @example
+     * ```typescript
+     * await user.restore()
+     * ```
+     */
+    restore(): Promise<boolean>;
+    /**
+     * Force a hard delete even if soft deletes are enabled.
+     *
+     * @returns A promise that resolves to true
+     *
+     * @example
+     * ```typescript
+     * await user.forceDelete()
+     * ```
+     */
+    forceDelete(): Promise<boolean>;
+    /**
+     * Refresh the model instance with fresh data from the database.
+     *
+     * @returns A promise that resolves to the model instance
+     *
+     * @example
+     * ```typescript
+     * await user.refresh()
+     * ```
+     */
+    refresh(): Promise<this>;
+}

package/dist/atlas/src/orm/model/concerns/HasRelationships.d.ts

@@ -0,0 +1,117 @@
+import type { Model, ModelConstructor } from '../Model';
+/**
+ * HasRelationships Concern
+ * @description Provides relationship management functionality including defining and loading relationships.
+ */
+export declare class HasRelationships {
+    /**
+     * Define a one-to-many relationship.
+     * Returns a QueryBuilder scoped to the related records.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param foreignKey - The foreign key on the related table.
+     * @param localKey - The local key on this table.
+     * @returns A QueryBuilder for the related model.
+     * @example
+     * ```typescript
+     * const posts = await user.hasMany(Post).where('published', true).get()
+     * ```
+     */
+    hasMany<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define a one-to-one relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param foreignKey - The foreign key on the related table.
+     * @param localKey - The local key on this table.
+     * @returns A QueryBuilder for the related model, limited to 1 result.
+     */
+    hasOne<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define an inverse one-to-one or one-to-many relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param foreignKey - The foreign key on this table.
+     * @param ownerKey - The owner key on the related table.
+     * @returns A QueryBuilder for the related model.
+     * @example
+     * ```typescript
+     * const user = await post.belongsTo(User).first()
+     * ```
+     */
+    belongsTo<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, ownerKey?: string): any;
+    /**
+     * Define a many-to-many relationship through a pivot table.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param pivotTable - The name of the join table.
+     * @param foreignPivotKey - The key on the pivot table pointing to this model.
+     * @param relatedPivotKey - The key on the pivot table pointing to the related model.
+     * @param localKey - The local key on this table.
+     * @param relatedKey - The related key on the related table.
+     * @returns Promise resolving to an array of related models.
+     */
+    belongsToMany<R extends Model>(related: ModelConstructor<R> & typeof Model, pivotTable: string, foreignPivotKey?: string, relatedPivotKey?: string, localKey?: string, relatedKey?: string): Promise<R[]>;
+    /**
+     * Stream hasMany relationship with cursor-based iteration
+     * Memory-safe for large relationship sets
+     *
+     * @example
+     * ```typescript
+     * for await (const posts of user.hasManyStream(Post, 'user_id', 100)) {
+     *   for (const post of posts) {
+     *     await processPost(post)
+     *   }
+     * }
+     * ```
+     */
+    hasManyStream<R extends Model>(related: ModelConstructor<R> & typeof Model, foreignKey?: string, chunkSize?: number, localKey?: string): AsyncGenerator<R[], void, unknown>;
+    /**
+     * Define a polymorphic one-to-one relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param name - The polymorphic relationship name (used to derive type and id fields).
+     * @param foreignKey - Optional explicit foreign key.
+     * @param localKey - Optional explicit local key.
+     * @returns A QueryBuilder for the related model.
+     */
+    morphOne<R extends Model>(related: ModelConstructor<R> & typeof Model, name: string, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define a polymorphic one-to-many relationship.
+     *
+     * @template R - The related model type.
+     * @param related - The related model constructor.
+     * @param name - The polymorphic relationship name.
+     * @param foreignKey - Optional explicit foreign key.
+     * @param localKey - Optional explicit local key.
+     * @returns A QueryBuilder for the related model.
+     */
+    morphMany<R extends Model>(related: ModelConstructor<R> & typeof Model, name: string, foreignKey?: string, localKey?: string): any;
+    /**
+     * Define a polymorphic inverse relationship.
+     *
+     * @template R - The related model type.
+     * @param name - The polymorphic relationship name.
+     * @param typeField - Optional explicit type field name.
+     * @param idField - Optional explicit ID field name.
+     * @returns A QueryBuilder for the resolved related model, or null if not resolvable.
+     */
+    morphTo<R extends Model>(name: string, typeField?: string, idField?: string): any;
+    /**
+     * Lazy load relationships for the current model
+     * @example await user.load('posts')
+     */
+    load(relation: string | string[]): Promise<this>;
+    /**
+     * Alias for load(), used for fluent eager loading on an instance.
+     *
+     * @param relation - The relationship name or an array of names
+     * @returns A promise that resolves to the model instance
+     */
+    with(relation: string | string[]): Promise<this>;
+}

package/dist/atlas/src/orm/model/concerns/HasSerialization.d.ts

@@ -0,0 +1,64 @@
+/**
+ * HasSerialization Concern
+ * @description Provides serialization functionality including converting to JSON, array/object, and handling hidden/appended attributes.
+ */
+export declare class HasSerialization {
+    /**
+     * Fill the model instance with an object of attributes.
+     *
+     * @param attributes - Key-value pairs of attributes to set
+     * @returns The model instance
+     *
+     * @example
+     * ```typescript
+     * user.fill({ name: 'Carl', email: 'carl@example.com' })
+     * ```
+     */
+    fill(attributes: Record<string, unknown>): this;
+    /**
+     * Convert the model instance to a JSON string.
+     *
+     * @returns A JSON string representation of the model
+     *
+     * @example
+     * ```typescript
+     * const json = user.toJSON()
+     * ```
+     */
+    toJSON(): unknown;
+    /**
+     * Convert the model instance to a plain JavaScript object.
+     * Alias for `toJSON()`.
+     *
+     * @returns A plain object representation of the model
+     */
+    toObject(): Record<string, unknown>;
+    /**
+     * Convert the model instance to a plain JavaScript object.
+     * Alias for `toJSON()`.
+     *
+     * @returns A plain object representation of the model
+     */
+    toArray(): Record<string, unknown>;
+    /**
+     * Get all attributes currently set on the model.
+     *
+     * @returns An object containing all model attributes
+     * @internal
+     */
+    getAttributes(): Record<string, unknown>;
+    /**
+     * Get a specific attribute value.
+     *
+     * @param key - The attribute name
+     * @returns The attribute value
+     * @internal
+     */
+    getAttribute(key: string): unknown;
+    /**
+     * Get the string representation of the model.
+     *
+     * @returns A JSON string representation of the model
+     */
+    toString(): string;
+}

package/dist/atlas/src/orm/model/concerns/applyMixins.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mixin utility for composing classes with multiple concerns.
+ * @description Utility function to copy properties from mixin prototypes to a base class prototype.
+ *
+ * @param base - Base class to extend
+ * @param mixins - Mixin classes to apply
+ * @returns Combined class with all mixin properties
+ *
+ * @example
+ * ```typescript
+ * class MyModel extends Model {}
+ * applyMixins(MyModel, [HasAttributes, HasEvents])
+ * ```
+ */
+export declare function applyMixins<T extends new (...args: unknown[]) => unknown, U extends (new (...args: unknown[]) => unknown)[]>(base: T, mixins: U): T & U[number];

package/dist/atlas/src/orm/model/concerns/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Concerns Index
+ *
+ * Re-exports all model concerns for easier importing.
+ */
+export { applyMixins } from './applyMixins';
+export type { ModelAttributes } from './HasAttributes';
+export { HasAttributes } from './HasAttributes';
+export { HasEvents } from './HasEvents';
+export { HasPersistence } from './HasPersistence';
+export { HasRelationships } from './HasRelationships';
+export { HasSerialization } from './HasSerialization';

package/dist/atlas/src/orm/model/decorators.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Options for the SoftDeletes decorator.
+ */
+export interface SoftDeletesOptions {
+    /**
+     * The name of the column used to store the deletion timestamp.
+     * @default 'deleted_at'
+     */
+    column?: string;
+}
+/**
+ * Meta keys for decorators
+ */
+/**
+ * Metadata key for Soft Deletes configuration.
+ * @internal
+ */
+export declare const SOFT_DELETES_KEY: unique symbol;
+/**
+ * Metadata key for Column definitions.
+ * @internal
+ */
+export declare const COLUMN_KEY: unique symbol;
+/**
+ * Metadata key for Version column.
+ * @internal
+ */
+export declare const VERSION_KEY: unique symbol;
+/**
+ * Metadata key for Sharded configuration.
+ * @internal
+ */
+export declare const SHARDED_KEY: unique symbol;
+/**
+ * Options for the Sharded decorator.
+ */
+export interface ShardedOptions {
+    /**
+     * The name of the ShardingManager to use.
+     * @default 'default'
+     */
+    manager?: string;
+    /**
+     * The property name of the shard key (e.g. 'tenantId').
+     */
+    key: string;
+}
+/**
+ * Sharded Decorator
+ *
+ * Marks a model as being horizontally sharded across multiple databases.
+ * Active Record operations will automatically route to the correct connection
+ * based on the shard key provided.
+ *
+ * @param options - Configuration for sharding containing the distribution key
+ */
+export declare function sharded(options: ShardedOptions): ClassDecorator;
+/**
+ * Soft Deletes Decorator
+ *
+ * Automatically adds a global scope to filter out deleted records.
+ * When applied to a Model class, it ensures that queries only return records
+ * where the deletion column (default 'deleted_at') is null.
+ *
+ * @param options - Configuration for soft deletes
+ *
+ * @example
+ * ```typescript
+ * @SoftDeletes({ column: 'deleted_at' })
+ * class User extends Model {
+ *   @column()
+ *   declare deletedAt: Date | null
+ * }
+ * ```
+ */
+export declare function SoftDeletes(options?: SoftDeletesOptions): ClassDecorator;
+/**
+ * Options for the Column decorator.
+ */
+export interface ColumnOptions {
+    /**
+     * Whether the column is a primary key.
+     * @default false
+     */
+    isPrimary?: boolean;
+    /**
+     * Whether the column should be automatically populated with a timestamp on creation.
+     * @default false
+     */
+    autoCreate?: boolean;
+    /**
+     * Whether the column should be automatically updated with a timestamp on every update.
+     * @default false
+     */
+    autoUpdate?: boolean;
+    /**
+     * The name of the column in the database.
+     * If not provided, the property name will be used.
+     */
+    name?: string;
+    /**
+     * The name to use when serializing the model to JSON.
+     * Set to null to hide the column from JSON output.
+     */
+    serializeAs?: string | null;
+}
+/**
+ * Column Decorator
+ *
+ * Marks a property as a database column. This decorator also triggers
+ * the registration of the model in the global ModelRegistry.
+ *
+ * @param options - Configuration for the column
+ *
+ * @example
+ * ```typescript
+ * class User extends Model {
+ *   @column({ isPrimary: true })
+ *   declare id: number
+ *
+ *   @column({ name: 'email_address' })
+ *   declare email: string
+ *
+ *   @column.dateTime({ autoCreate: true })
+ *   declare createdAt: Date
+ * }
+ * ```
+ */
+export declare function column(options?: ColumnOptions): PropertyDecorator;
+/**
+ * Version Decorator for Optimistic Locking
+ *
+ * Marks a property as a version column for optimistic locking.
+ * When a model updates, it checks if the version matches the one in the database.
+ *
+ * @param options - Configuration for the column (same as @column)
+ */
+export declare function version(options?: ColumnOptions): PropertyDecorator;

package/dist/atlas/src/orm/model/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Model Errors
+ * @description Custom error types for ORM model operations
+ */
+/**
+ * Column Not Found Error
+ * Thrown when accessing/setting a column that doesn't exist in schema
+ */
+export declare class ColumnNotFoundError extends Error {
+    readonly table: string;
+    readonly column: string;
+    constructor(table: string, column: string, availableColumns?: string[]);
+}
+/**
+ * Type Mismatch Error
+ * Thrown when setting a value with incompatible type
+ */
+export declare class TypeMismatchError extends Error {
+    readonly table: string;
+    readonly column: string;
+    readonly expectedType: string;
+    readonly actualType: string;
+    readonly value?: unknown | undefined;
+    constructor(table: string, column: string, expectedType: string, actualType: string, value?: unknown | undefined);
+}
+/**
+ * Nullable Constraint Error
+ * Thrown when setting null on a non-nullable column
+ */
+export declare class NullableConstraintError extends Error {
+    readonly table: string;
+    readonly column: string;
+    constructor(table: string, column: string);
+}
+/**
+ * Model Not Found Error
+ * Thrown when a model is not found in the database
+ */
+export declare class ModelNotFoundError extends Error {
+    readonly model: string;
+    readonly key: unknown;
+    constructor(model: string, key: unknown);
+}
+/**
+ * Stale Model Error
+ * Thrown when an optimistic lock check fails (concurrent update)
+ */
+export declare class StaleModelError extends Error {
+    readonly model: string;
+    readonly key: unknown;
+    constructor(model: string, key: unknown);
+}

package/dist/atlas/src/orm/model/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Model Module Index
+ */
+export { applyMixins, HasAttributes, HasEvents, HasPersistence, HasRelationships, HasSerialization, } from './concerns';
+export { DirtyTracker } from './DirtyTracker';
+export { column, SoftDeletes, sharded, version } from './decorators';
+export { ColumnNotFoundError, ModelNotFoundError, NullableConstraintError, TypeMismatchError, } from './errors';
+export { Model, type ModelAttributes, type ModelConstructor, type ModelStatic } from './Model';
+export { ModelRegistry } from './ModelRegistry';
+export { BelongsTo, BelongsToMany, eagerLoad, eagerLoadMany, getRelationships, HasMany, HasOne, MorphMany, MorphOne, MorphTo, type RelationshipMeta, type RelationshipOptions, type RelationType, } from './relationships';