@c15t/backend 0.0.1-rc.10

package/src/db/core/fields/field-inference.ts

@@ -0,0 +1,298 @@
+import type {
+	InferValueType as BaseInferValueType,
+	Field,
+	FieldType,
+	Primitive,
+} from './field-types';
+
+/**
+ * Infers the JavaScript type from a field type.
+ * Maps database field types to their corresponding TypeScript types.
+ *
+ * @template TFieldType - The field type to infer from
+ *
+ * @example
+ * ```typescript
+ * // Infer string type
+ * type NameType = InferValueType<'string'>;  // string
+ *
+ * // Infer array types
+ * type TagsType = InferValueType<'string[]'>;  // string[]
+ * type FlagsType = InferValueType<'boolean[]'>;  // boolean[]
+ * type DatesType = InferValueType<'date[]'>;  // Date[]
+ * ```
+ *
+ * @remarks
+ * This type handles both scalar types and array types.
+ * For arrays, it maps the base type to an array of that type.
+ * This approach is more maintainable and future-proof than
+ * explicitly handling each array type.
+ */
+export type InferValueType<TFieldType extends FieldType> =
+	BaseInferValueType<TFieldType>;
+
+/**
+ * Infers the output type for a single field.
+ * Takes into account whether the field is required and returned in API responses.
+ *
+ * @template TField - The field definition
+ *
+ * @example
+ * ```typescript
+ * // A required string field
+ * const nameField: Field<'string'> = {
+ *   type: 'string',
+ *   required: true
+ * };
+ * type NameOutput = InferFieldOutput<typeof nameField>;  // string
+ *
+ * // An optional number field
+ * const ageField: Field<'number'> = {
+ *   type: 'number',
+ *   required: false
+ * };
+ * type AgeOutput = InferFieldOutput<typeof ageField>;  // number | null | undefined
+ * ```
+ *
+ * @remarks
+ * If a field has `returned: false`, this will be `never` indicating
+ * the field should not appear in API responses.
+ */
+export type InferFieldOutput<TField extends Field> =
+	TField['returned'] extends false
+		? never
+		: TField['required'] extends false
+			? InferValueType<TField['type']> | null | undefined
+			: InferValueType<TField['type']>;
+
+/**
+ * Infers the input type for a single field.
+ * Determines the expected type when creating or updating records.
+ *
+ * @template TField - The field definition
+ *
+ * @example
+ * ```typescript
+ * // A non-input field (system-generated)
+ * const createdAtField: Field<'date'> = {
+ *   type: 'date',
+ *   required: true,
+ *   input: false
+ * };
+ * type CreatedAtInput = InferFieldInput<typeof createdAtField>;  // never
+ * ```
+ *
+ * @remarks
+ * If a field has `input: false`, this will be `never` indicating
+ * the field should not be provided in API requests.
+ */
+export type InferFieldInput<TField extends Field> =
+	TField['input'] extends false
+		? never
+		: TField['required'] extends true
+			? InferValueType<TField['type']>
+			: InferValueType<TField['type']> | null | undefined;
+
+/**
+ * Type-safe property mapping helper for field outputs.
+ * Maps properties of a record type to their corresponding output types.
+ *
+ * @template TSchema - The record type containing field definitions
+ * @template TKey - The keys of TSchema to map
+ *
+ * @internal
+ * This is an internal helper type used by InferFieldsOutput
+ */
+// type MapToFieldOutputType<TSchema, TKey extends keyof TSchema & string> = {
+// 	[Property in TKey]: TSchema[Property] extends Field
+// 		? InferFieldOutput<TSchema[Property]>
+// 		: never;
+// };
+
+// /**
+//  * Type-safe property mapping helper for field inputs.
+//  * Maps properties of a record type to their corresponding input types.
+//  *
+//  * @template TSchema - The record type containing field definitions
+//  * @template TKey - The keys of TSchema to map
+//  *
+//  * @internal
+//  * This is an internal helper type used by InferFieldsInput
+//  */
+// type MapToFieldInputType<TSchema, TKey extends keyof TSchema & string> = {
+// 	[Property in TKey]: TSchema[Property] extends Field
+// 		? InferFieldInput<TSchema[Property]>
+// 		: never;
+// };
+
+/**
+ * Type helper to extract required keys from fields that should be returned.
+ * Identifies fields that are both required and returned in API responses.
+ *
+ * @template TSchema - The record type containing field definitions
+ *
+ * @internal
+ * Used to determine which fields must be present in output types
+ */
+type RequiredKeys<TSchema> = {
+	[Key in keyof TSchema]: TSchema[Key] extends Field
+		? TSchema[Key]['required'] extends true
+			? TSchema[Key]['returned'] extends false
+				? never
+				: Key
+			: never
+		: never;
+}[keyof TSchema];
+
+/**
+ * Type helper to extract optional keys from fields that should be returned.
+ * Identifies fields that are optional but should be returned in API responses.
+ *
+ * @template TSchema - The record type containing field definitions
+ *
+ * @internal
+ * Used to determine which fields may be present in output types
+ */
+type OptionalKeys<TSchema> = {
+	[Key in keyof TSchema]: TSchema[Key] extends Field
+		? TSchema[Key]['required'] extends true
+			? never
+			: TSchema[Key]['returned'] extends false
+				? never
+				: Key
+		: never;
+}[keyof TSchema];
+
+/**
+ * Type helper to extract required keys from fields that accept input.
+ * Identifies fields that are both required and accept subject input.
+ *
+ * @template TSchema - The record type containing field definitions
+ *
+ * @internal
+ * Used to determine which fields must be provided in create operations
+ */
+type RequiredInputKeys<TSchema> = {
+	[Key in keyof TSchema]: TSchema[Key] extends Field
+		? TSchema[Key]['required'] extends true
+			? TSchema[Key]['input'] extends false
+				? never
+				: Key
+			: never
+		: never;
+}[keyof TSchema];
+
+/**
+ * Type helper to extract optional keys from fields that accept input.
+ * Identifies fields that are optional and accept subject input.
+ *
+ * @template TSchema - The record type containing field definitions
+ *
+ * @internal
+ * Used to determine which fields may be provided in create operations
+ */
+type OptionalInputKeys<TSchema> = {
+	[Key in keyof TSchema]: TSchema[Key] extends Field
+		? TSchema[Key]['required'] extends true
+			? never
+			: TSchema[Key]['input'] extends false
+				? never
+				: Key
+		: never;
+}[keyof TSchema];
+
+/**
+ * Infers the output type shape for a set of fields.
+ * Handles required/optional status and returned fields.
+ * Used to determine the shape of data when retrieving records.
+ *
+ * @template TSchema - The field definitions to infer from
+ *
+ * @example
+ * ```typescript
+ * // Define a schema
+ * const subjectSchema = {
+ *   id: stringField({ required: true }),
+ *   name: stringField({ required: true }),
+ *   email: stringField({ required: true }),
+ *   age: numberField({ required: false }),
+ *   password: stringField({ required: true, returned: false })
+ * };
+ *
+ * // Infer the output type (for API responses)
+ * type SubjectOutput = InferFieldsOutput<typeof subjectSchema>;
+ * // Result: { id: string; name: string; email: string; age?: number | null | undefined }
+ * // Note: 'password' is excluded because returned: false
+ * ```
+ *
+ * @remarks
+ * This creates a type with:
+ * - Required properties for fields marked required and returned
+ * - Optional properties for fields marked optional and returned
+ * - Excludes fields marked with returned: false
+ */
+export type InferFieldsOutput<TSchema> = TSchema extends Record<string, Field>
+	? {
+			[Key in RequiredKeys<TSchema> & string]: InferFieldOutput<TSchema[Key]>;
+		} & {
+			[Key in OptionalKeys<TSchema> & string]?: InferFieldOutput<TSchema[Key]>;
+		}
+	: Record<string, never>;
+
+/**
+ * Infers the input type shape for a set of fields.
+ * Handles required/optional status and input fields.
+ * Used to determine the shape of data expected when creating records.
+ *
+ * @template TSchema - The field definitions to infer from
+ *
+ * @example
+ * ```typescript
+ * // Define a schema
+ * const subjectSchema = {
+ *   id: stringField({ required: true, input: false }), // Auto-generated
+ *   name: stringField({ required: true }),
+ *   email: stringField({ required: true }),
+ *   age: numberField({ required: false }),
+ *   createdAt: dateField({ required: true, input: false })
+ * };
+ *
+ * // Infer the input type (for create operations)
+ * type SubjectInput = InferFieldsInput<typeof subjectSchema>;
+ * // Result: { name: string; email: string; age?: number | null | undefined }
+ * // Note: 'id' and 'createdAt' are excluded because input: false
+ * ```
+ *
+ * @remarks
+ * This creates a type with:
+ * - Required properties for fields marked required and input
+ * - Optional properties for fields marked optional and input
+ * - Excludes fields marked with input: false
+ */
+export type InferFieldsInput<TSchema> = TSchema extends Record<string, Field>
+	? {
+			[Key in RequiredInputKeys<TSchema> & string]: InferFieldInput<
+				TSchema[Key]
+			>;
+		} & {
+			[Key in OptionalInputKeys<TSchema> & string]?: InferFieldInput<
+				TSchema[Key]
+			>;
+		}
+	: Record<string, never>;
+
+/**
+ * Type helper for transform function output based on field type.
+ * Ensures transform functions return the correct output type.
+ *
+ * @template TFieldType - The field type that determines the input parameter type
+ *
+ * @example
+ * ```typescript
+ * const dateTransform: TransformOutputFn<'date'> = (value) => value.toISOString();
+ * // value is typed as Date
+ * ```
+ */
+export type TransformOutputFn<TFieldType extends FieldType> = (
+	value: InferValueType<TFieldType>
+) => Primitive | Promise<Primitive>;

package/src/db/core/fields/field-options-integration.ts

@@ -0,0 +1,135 @@
+import type { C15TOptions } from '~/types';
+import type { InferFieldsInput, InferFieldsOutput } from './field-inference';
+import type { Field } from './field-types';
+
+/**
+ * Infers field types from plugin definitions in C15T options.
+ * Extracts and combines field definitions from enabled plugins.
+ *
+ * @template TOptions - The C15T options configuration type
+ * @template TSchemaKey - Key for accessing the specific entity schema within plugins
+ * @template TFormat - Format to return ('output' or 'input')
+ *
+ * @example
+ * ```typescript
+ * // Configuration with plugins defining consent fields
+ * interface MyOptions extends C15TOptions {
+ *   auth: {
+ *     plugins: {
+ *       consent: {
+ *         enabled: true,
+ *         subjectFields: {
+ *           acceptedTerms: {
+ *             type: 'boolean',
+ *             required: true
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * // Infer the output types for subject fields from plugins
+ * type SubjectPluginFields = InferFieldsFromPlugins<MyOptions, 'subjectFields', 'output'>;
+ * // Results in { acceptedTerms: boolean }
+ * ```
+ *
+ * @remarks
+ * This type helper allows plugins to extend entity schemas with their own fields.
+ * It walks through all enabled plugins, extracts fields for the specified entity type,
+ * and combines them into a single type.
+ */
+export type InferFieldsFromPlugins<
+	TOptions extends C15TOptions,
+	TSchemaKey extends string,
+	TFormat extends 'output' | 'input' = 'output',
+> = InferFieldsFromObjectPath<
+	TOptions,
+	[string, 'plugins', string, TSchemaKey],
+	TFormat
+>;
+
+/**
+ * Infers field types from C15T options for a specific module.
+ * Used to extract additional fields defined in options.
+ *
+ * @template TOptions - The C15T options configuration type
+ * @template TSchemaKey - Key for accessing the specific entity schema
+ * @template TFormat - Format to return ('output' or 'input')
+ *
+ * @example
+ * ```typescript
+ * // Configuration with additional subject fields
+ * interface MyOptions extends C15TOptions {
+ *   auth: {
+ *     subjectFields: {
+ *       profile: {
+ *         type: 'string',
+ *         required: false
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * // Infer the output types for subject fields from options
+ * type SubjectAdditionalFields = InferFieldsFromOptions<MyOptions, 'subject', 'subjectFields', 'output'>;
+ * // Results in { profile?: string | null | undefined }
+ * ```
+ *
+ * @remarks
+ * TSchemaKey can be one of:
+ * - Single string key like 'subjectFields' to access TOptions[T]['subjectFields']
+ * - Array of strings for a nested path like ['subject', 'subjectFields']
+ *
+ * This type helper extracts custom fields defined directly in the options object,
+ * rather than those defined in plugins.
+ */
+export type InferFieldsFromOptions<
+	TOptions extends C15TOptions,
+	TModuleKey extends keyof TOptions & string,
+	TSchemaKey extends string,
+	TFormat extends 'output' | 'input' = 'output',
+> = InferFieldsFromObjectPath<TOptions, [TModuleKey, TSchemaKey], TFormat>;
+
+// Internal helper type
+type InferFieldsFromObjectPath<
+	TOptions,
+	TPath extends (string | number)[],
+	TFormat extends 'output' | 'input',
+> = TFormat extends 'output'
+	? InferFieldsOutput<GetFieldsFromPath<TOptions, TPath>>
+	: InferFieldsInput<GetFieldsFromPath<TOptions, TPath>>;
+
+// Internal helper type for accessing nested paths
+type GetFieldsFromPath<
+	TOptions,
+	TPath extends (string | number)[],
+> = TPath extends [infer TFirst, ...infer TRest]
+	? TFirst extends keyof TOptions
+		? TRest extends (string | number)[]
+			? TRest['length'] extends 0
+				? TOptions[TFirst] extends Record<string, Field>
+					? TOptions[TFirst]
+					: never
+				: GetFieldsFromPath<TOptions[TFirst], TRest>
+			: never
+		: TFirst extends string
+			? TOptions extends Record<string, unknown>
+				? TRest extends (string | number)[]
+					? TRest['length'] extends 0
+						? {
+								[K in keyof TOptions]: K extends TFirst
+									? TOptions[K] extends Record<string, Field>
+										? TOptions[K]
+										: never
+									: never;
+							}[keyof TOptions & TFirst]
+						: {
+								[K in keyof TOptions]: K extends TFirst
+									? GetFieldsFromPath<TOptions[K], TRest>
+									: never;
+							}[keyof TOptions & TFirst]
+					: never
+				: never
+			: never
+	: Record<string, never>;

package/src/db/core/fields/field-types.ts

@@ -0,0 +1,233 @@
+/**
+ * The set of field types supported by C15T.
+ * Specifies the data types that can be used for database fields.
+ *
+ * @remarks
+ * These types determine how data is stored, validated, and transformed.
+ * The system supports both scalar types and array types.
+ */
+export type FieldType =
+	| 'string'
+	| 'number'
+	| 'boolean'
+	| 'date'
+	| 'timezone'
+	| 'json'
+	| 'string[]'
+	| 'number[]';
+
+/**
+ * Primitive types that can be stored in the database.
+ */
+export type Primitive = string | number | boolean | Date | null | undefined;
+
+/**
+ * JSON value types that can be stored in JSON fields.
+ */
+export type JsonValue =
+	| string
+	| number
+	| boolean
+	| null
+	| JsonValue[]
+	| { [key: string]: JsonValue };
+
+/**
+ * Configuration options for a database field.
+ * Defines the behavior, validation, and transformations for a field.
+ *
+ * @template TFieldType - The data type of the field
+ *
+ * @example
+ * ```typescript
+ * // Basic required string field
+ * const basicConfig: FieldConfig<'string'> = {
+ *   type: 'string',
+ *   required: true
+ * };
+ *
+ * // Optional number field with validation
+ * const numberConfig: FieldConfig<'number'> = {
+ *   type: 'number',
+ *   required: false,
+ *   validator: (value) => value >= 0 ? null : 'Must be non-negative'
+ * };
+ *
+ * // Date field with transform and default
+ * const dateConfig: FieldConfig<'date'> = {
+ *   type: 'date',
+ *   defaultValue: () => new Date(),
+ *   transform: {
+ *     output: (date) => date.toISOString()
+ *   }
+ * };
+ * ```
+ *
+ * @remarks
+ * This is the core configuration object that defines how a field behaves
+ * in the database schema. It controls whether the field is required, how
+ * it's transformed, validated, and more.
+ */
+export type FieldConfig<TFieldType extends FieldType> = {
+	/**
+	 * The data type of the field.
+	 * Determines how the field is stored and validated.
+	 */
+	type: TFieldType;
+
+	/**
+	 * Whether the field is required for record creation.
+	 * If true, the field must be provided when creating a record.
+	 * @default true
+	 */
+	required?: boolean;
+
+	/**
+	 * Whether the field should be returned in API responses.
+	 * If false, the field will be excluded from query results.
+	 * @default true
+	 */
+	returned?: boolean;
+
+	/**
+	 * Whether the field accepts input from API requests.
+	 * If false, the field cannot be set directly by clients.
+	 * @default true
+	 */
+	input?: boolean;
+
+	/**
+	 * Default value for the field when not provided in create operations.
+	 * Can be a static value or a function that returns a value.
+	 */
+	defaultValue?: Primitive | (() => Primitive);
+
+	/**
+	 * Functions to transform the field value during input/output operations.
+	 * Can modify values before storage or after retrieval.
+	 */
+	transform?: {
+		/**
+		 * Transform function for field input.
+		 * Applied when data is being saved to the database.
+		 */
+		input?: (
+			value: InferValueType<TFieldType>
+		) => Primitive | Promise<Primitive>;
+
+		/**
+		 * Transform function for field output.
+		 * Applied when data is being retrieved from the database.
+		 */
+		output?: (
+			value: unknown
+		) => InferValueType<TFieldType> | Promise<InferValueType<TFieldType>>;
+	};
+
+	/**
+	 * Custom validation function for the field.
+	 * Returns null if valid, or an error message if invalid.
+	 */
+	validator?: (value: InferValueType<TFieldType>) => string | null;
+
+	/**
+	 * Whether the field should be unique across all records.
+	 * If true, no two records can have the same value for this field.
+	 */
+	unique?: boolean;
+
+	/**
+	 * Whether the field should be indexed for faster lookups.
+	 * If true, an index will be created for this field.
+	 */
+	indexed?: boolean;
+
+	/**
+	 * Whether the field should be sortable in queries.
+	 * If false, the field cannot be used in ORDER BY clauses.
+	 * @default true
+	 */
+	sortable?: boolean;
+
+	/**
+	 * Custom database field name.
+	 * If not provided, the field name will be used as-is.
+	 */
+	fieldName?: string;
+
+	/**
+	 * Whether the field should be stored as a bigint.
+	 * Only applicable to number fields.
+	 * @default false
+	 */
+	bigint?: boolean;
+
+	/**
+	 * References to other models.
+	 */
+	references?: {
+		model: string;
+		entity: string;
+		field: string;
+		onDelete: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+	};
+};
+
+/**
+ * Helper type to infer the base JavaScript type from a field type.
+ */
+export type InferValueType<TFieldType extends FieldType> =
+	TFieldType extends 'string'
+		? string
+		: TFieldType extends 'number'
+			? number
+			: TFieldType extends 'boolean'
+				? boolean
+				: TFieldType extends 'date'
+					? Date
+					: TFieldType extends 'timezone'
+						? string
+						: TFieldType extends 'json'
+							? JsonValue
+							: TFieldType extends 'string[]'
+								? string[]
+								: TFieldType extends 'number[]'
+									? number[]
+									: never;
+
+/**
+ * The complete definition of a database field.
+ * Combines the field type with its configuration options.
+ *
+ * @template TFieldType - The data type of the field
+ *
+ * @example
+ * ```typescript
+ * // A simple string field
+ * const nameField: Field<'string'> = {
+ *   type: 'string',
+ *   required: true,
+ *   unique: true
+ * };
+ *
+ * // A number field with validation
+ * const ageField: Field<'number'> = {
+ *   type: 'number',
+ *   required: true,
+ *   validator: (value) => value >= 0 ? null : 'Age must be non-negative'
+ * };
+ *
+ * // A date field with transforms
+ * const createdAtField: Field<'date'> = {
+ *   type: 'date',
+ *   required: true,
+ *   input: false,
+ *   defaultValue: () => new Date(),
+ *   transform: {
+ *     output: (date) => date.toISOString()
+ *   }
+ * };
+ * ```
+ */
+export type Field<TFieldType extends FieldType = FieldType> =
+	FieldConfig<TFieldType>;