@c15t/backend 0.0.1-rc.10

package/src/db/adapters/types.ts

@@ -0,0 +1,203 @@
+import type { C15TOptions } from '~/types';
+import type { EntityInput, EntityName } from '../core/types';
+import type { C15TDBSchema } from '../schema/definition';
+import type { KyselyAdapterConfig } from './kysely-adapter';
+
+/**
+ * Type representing the fields of a database table for a specific entity
+ */
+export type TableFields<EntityType extends EntityName> =
+	C15TDBSchema[EntityType]['fields'];
+
+/**
+ * Type representing the possible value types that can be used in query conditions
+ */
+export type Value =
+	| string
+	| number
+	| boolean
+	| string[]
+	| number[]
+	| Date
+	| null;
+
+/**
+ * Type representing the comparison operators available for query conditions
+ */
+export type ComparisonOperator =
+	| 'eq' // Equal to
+	| 'ne' // Not equal to
+	| 'lt' // Less than
+	| 'lte' // Less than or equal to
+	| 'gt' // Greater than
+	| 'gte' // Greater than or equal to
+	| 'in' // In array
+	| 'contains' // Contains substring
+	| 'starts_with' // Starts with
+	| 'ends_with' // Ends with
+	| 'ilike'; // Case insensitive equality
+
+/**
+ * Type representing the logical connectors for combining query conditions
+ */
+export type LogicalConnector = 'AND' | 'OR';
+
+/**
+ * Type representing a single query condition
+ */
+export type WhereCondition<EntityType extends EntityName> = {
+	/** The comparison operator to use (defaults to 'eq') */
+	operator?: ComparisonOperator;
+	/** The value to compare against */
+	value: Value;
+	/** The field to apply the condition to */
+	field: keyof TableFields<EntityType> | 'id';
+	/** The logical connector to use with previous conditions (defaults to 'AND') */
+	connector?: LogicalConnector;
+};
+
+/**
+ * Type representing a complete where clause for database queries
+ */
+export type Where<EntityType extends EntityName> = WhereCondition<EntityType>[];
+
+/**
+ * Type representing sorting options for queries
+ */
+export type SortOptions<EntityType extends EntityName> = {
+	/** The field to sort by */
+	field: keyof TableFields<EntityType> | 'id';
+	/** The sort direction */
+	direction: 'asc' | 'desc';
+};
+
+/**
+ * Type representing the result of a schema creation operation
+ */
+export type AdapterSchemaCreation = {
+	/** The code to be inserted into the file */
+	code: string;
+	/** The path to the file */
+	path: string;
+	/** Whether to append to existing file */
+	append?: boolean;
+	/** Whether to overwrite existing file */
+	overwrite?: boolean;
+};
+
+/**
+ * Interface defining the contract for database adapters
+ */
+export interface Adapter {
+	/** Unique identifier for the adapter */
+	id: string;
+
+	/** Creates a new record in the database */
+	create: <
+		Model extends EntityName,
+		Data extends Record<string, unknown>,
+		Result extends TableFields<Model>,
+	>(data: {
+		model: Model;
+		data: Data;
+		select?: Array<keyof Result>;
+	}) => Promise<Result>;
+
+	/** Finds a single record matching the where conditions */
+	findOne: <Model extends EntityName, Result extends TableFields<Model>>(data: {
+		model: Model;
+		where: Where<Model>;
+		select?: Array<keyof Result>;
+		sortBy?: SortOptions<Model>;
+	}) => Promise<Result | null>;
+
+	/** Finds multiple records matching the where conditions */
+	findMany: <Model extends EntityName>(data: {
+		model: Model;
+		where?: Where<Model>;
+		limit?: number;
+		sortBy?: SortOptions<Model>;
+		offset?: number;
+	}) => Promise<TableFields<Model>[]>;
+
+	/** Counts records matching the where conditions */
+	count: <Model extends EntityName>(data: {
+		model: Model;
+		where?: Where<Model>;
+	}) => Promise<number>;
+
+	/** Updates a single record matching the where conditions */
+	update: <Model extends EntityName, Result extends TableFields<Model>>(data: {
+		model: Model;
+		where: Where<Model>;
+		update: EntityInput<Model>;
+	}) => Promise<Result | null>;
+
+	/** Updates multiple records matching the where conditions */
+	updateMany: <
+		Model extends EntityName,
+		Result extends TableFields<Model>,
+	>(data: {
+		model: Model;
+		where: Where<Model>;
+		update: Partial<EntityInput<Model>>;
+	}) => Promise<Result[]>;
+
+	/** Deletes a single record matching the where conditions */
+	delete: <Model extends EntityName>(data: {
+		model: Model;
+		where: Where<Model>;
+	}) => Promise<void>;
+
+	/** Deletes multiple records matching the where conditions */
+	deleteMany: <Model extends EntityName>(data: {
+		model: Model;
+		where: Where<Model>;
+	}) => Promise<number>;
+
+	/**
+	 * Executes a function within a database transaction
+	 *
+	 * This method allows multiple database operations to be executed in a single atomic transaction.
+	 * If any operation within the transaction fails, all operations are rolled back.
+	 *
+	 * @typeParam ResultType - The type of data returned by the transaction
+	 * @param data - The transaction data containing the callback function
+	 * @returns A promise that resolves with the result of the callback function
+	 * @throws {Error} If the transaction fails to complete
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await adapter.transaction({
+	 *   callback: async (tx) => {
+	 *     const subject = await tx.create({
+	 *       model: 'subject',
+	 *       data: { name: 'John Doe' }
+	 *     });
+	 *     await tx.create({
+	 *       model: 'profile',
+	 *       data: { subjectId: subject.id, bio: 'Test bio' }
+	 *     });
+	 *     return subject;
+	 *   }
+	 * });
+	 * ```
+	 */
+	transaction: <ResultType>(data: {
+		callback: (transactionAdapter: Adapter) => Promise<ResultType>;
+	}) => Promise<ResultType>;
+
+	/** Optional method to create database schema */
+	createSchema?: (
+		options: C15TOptions,
+		file?: string
+	) => Promise<AdapterSchemaCreation>;
+
+	/** Optional adapter-specific configuration */
+	options?: KyselyAdapterConfig | Record<string, unknown>;
+}
+
+/**
+ * Type definition for an adapter factory function
+ */
+export type AdapterInstance = (options: C15TOptions) => Adapter;

package/src/db/adapters/utils.ts

@@ -0,0 +1,51 @@
+import type { Field, Primitive } from '../core/fields/field-types';
+
+/**
+ * Applies the default value of a field if the provided value is undefined or null.
+ * Used in create and update operations to handle default values consistently.
+ *
+ * @typeParam PrimitiveValue - The primitive type of the field value
+ * @param inputValue - The input value provided for the field (may be undefined/null)
+ * @param field - The field definition containing the default value
+ * @param operation - The database operation being performed ('create' or 'update')
+ * @returns The original value, or the default value if applicable
+ *
+ * @remarks
+ * Default values are only applied:
+ * 1. During 'create' operations (not during updates)
+ * 2. When the input value is undefined or null
+ * 3. When the field has a defaultValue defined
+ *
+ * If the defaultValue is a function, it will be called to generate the value.
+ * This allows for dynamic default values such as timestamps, UUIDs, or any
+ * other values that need to be computed at runtime.
+ *
+ * @example
+ * ```typescript
+ * // Field with static default
+ * const nameField = { type: 'string', defaultValue: 'Anonymous' };
+ * applyDefaultValue(undefined, nameField, 'create'); // 'Anonymous'
+ * applyDefaultValue('Alice', nameField, 'create');   // 'Alice'
+ * applyDefaultValue(undefined, nameField, 'update'); // undefined
+ *
+ * // Field with dynamic default
+ * const createdField = { type: 'date', defaultValue: () => new Date() };
+ * applyDefaultValue(undefined, createdField, 'create'); // Current date
+ * ```
+ */
+export function applyDefaultValue(
+	inputValue: Primitive,
+	field: Field,
+	operation: 'create' | 'update'
+): Primitive {
+	if (operation === 'update') {
+		return inputValue;
+	}
+	if ((inputValue === undefined || inputValue === null) && field.defaultValue) {
+		if (typeof field.defaultValue === 'function') {
+			return field.defaultValue();
+		}
+		return field.defaultValue;
+	}
+	return inputValue;
+}