UNPKG

@palmares/databases

Version:

Add support for working with databases with palmares framework

501 lines 25.6 kB
import { TextField } from './text'; import type { CustomImportsForFieldType, FieldWithOperationTypeForSearch } from './types'; import type { CompareCallback, NewInstanceArgumentsCallback, OptionsCallback, ToStringCallback } from './utils'; import type { DatabaseAdapter } from '../../engine'; /** * Functional approach for the creation of a CharField. * * A CharField is a field that can hold Character values. On Relational Databases that would be a `VARCHAR` field. * A varchar should have a maximum length, so you should always define a `maxLength` for this field. * * @example * ```ts * const charField = char(); * ``` * * @example * ``` * const charField = char({ maxLen: 255 }).allowNull(); * ``` */ export declare function char<const TMaxCharLength extends number>(args: { maxLen: TMaxCharLength; }): CharField<{ create: string; read: string; update: string; }, { unique: false; allowNull: false; dbIndex: false; underscored: true; allowBlank: true; isPrimaryKey: false; auto: false; defaultValue: undefined; typeName: string; hasDefaultValue: false; databaseName: undefined; engineInstance: DatabaseAdapter; customAttributes: any; maxLength: TMaxCharLength; }, Pick<FieldWithOperationTypeForSearch<string>, 'like' | 'and' | 'in' | 'or' | 'eq' | 'is'>>; /** * A CharField supports either true or false. * * @example * ```ts * const booleanField = CharField.new(); * ``` * * @example * ``` * const booleanField = CharField.new({ databaseName: 'user_id' }); * ``` */ export declare class CharField<out TType extends { create: any; read: any; update: any; } = { create: string; read: string; update: string; }, out TDefinitions extends { unique: boolean; auto: boolean; allowNull: boolean; allowBlank: boolean; dbIndex: boolean; isPrimaryKey: boolean; defaultValue: undefined; underscored: boolean; typeName: string; hasDefaultValue: boolean; databaseName: string | undefined; engineInstance: DatabaseAdapter; customAttributes: any; maxLength: number; } = { unique: false; allowNull: false; allowBlank: true; dbIndex: false; underscored: true; isPrimaryKey: false; auto: false; hasDefaultValue: false; defaultValue: undefined; typeName: string; databaseName: undefined; engineInstance: DatabaseAdapter; customAttributes: any; maxLength: number; }, out TFieldOperationTypes = Pick<FieldWithOperationTypeForSearch<string>, 'like' | 'and' | 'in' | 'or' | 'eq' | 'is'>> extends TextField<TType, TDefinitions, TFieldOperationTypes> { protected $$type: string; protected __typeName: string; protected __allowedQueryOperations: Set<any>; protected __maxLength: TDefinitions['maxLength']; protected __inputParsers: Map<string, (args: import("../..").AdapterFieldParserInputAndOutputArgs<"field" | "auto" | "big-auto" | "big-integer" | "boolean" | "char" | "date" | "decimal" | "enum" | "foreign-key" | "integer" | "text" | "uuid">) => Promise<any>>; protected __outputParsers: Map<string, (args: import("../..").AdapterFieldParserInputAndOutputArgs<"field" | "auto" | "big-auto" | "big-integer" | "boolean" | "char" | "date" | "decimal" | "enum" | "foreign-key" | "integer" | "text" | "uuid">) => Promise<any>>; protected __getArgumentsCallback: (field: import("./field").Field<any, any, any>, defaultGetArgumentsCallback: typeof import("./utils").defaultGetArgumentsCallback) => { allowBlank: boolean; maxLength: number; $field: import("./field").Field<any, any, any>; $model: (import("../model").ModelType<any, any> & typeof import("..").Model & typeof import("..").BaseModel) | undefined; typeName: string; fieldName: string; modelName: string; isAuto: boolean; primaryKey: boolean; defaultValue: any; allowNull: boolean; unique: boolean; dbIndex: boolean; databaseName: string | undefined; underscored: boolean; customAttributes: unknown; }; protected __compareCallback: (engine: DatabaseAdapter<any, import("../..").AdapterFields, import("../..").AdapterModels<any>, import("../..").AdapterQuery, import("../..").AdapterMigrations>, oldField: import("./field").Field<any, any, any>, newField: import("./field").Field<any, any, any>, defaultCompareCallback: CompareCallback) => [boolean, string[]]; protected __optionsCallback: (setFieldValue: (hiddenFieldName: string, getArgumentsFieldName: string | undefined, value: any) => void, oldField: import("./field").Field<any, any, any>, defaultOptionsCallback: OptionsCallback) => void; protected __newInstanceCallback: (field: import("./field").Field<any, any, any>, defaultNewInstanceArgumentsCallback: NewInstanceArgumentsCallback) => any[]; /** * This is used internally by the engine to convert the field to string. * You can override this if you want to extend the ForeignKeyField class. */ protected __toStringCallback: (engine: DatabaseAdapter<any, import("../..").AdapterFields, import("../..").AdapterModels<any>, import("../..").AdapterQuery, import("../..").AdapterMigrations>, field: import("./field").Field<any, any, any>, defaultToStringCallback: ToStringCallback, _customParams?: { constructorParams?: string; builderParams?: string; } | undefined) => Promise<{ stringfied: string; customImports: CustomImportsForFieldType[]; }>; constructor(params: { maxLen: number; }); /** * Supposed to be used by library maintainers. * * When you custom create a field, you might want to take advantage of the builder pattern we already support. * This let's you create functions that can be chained together to create a new field. It should be used * alongside the `_setPartialAttributes` method like * * @example * ```ts * const customBigInt = CharField._overrideType< * { create: bigint; read: bigint; update: bigint }, * { * customAttributes: { name: string }; * unique: boolean; * auto: boolean; * allowNull: true; * dbIndex: boolean; * isPrimaryKey: boolean; * defaultValue: any; * typeName: string; * engineInstance: DatabaseAdapter; * } * >({ * typeName: 'CustomBigInt' * }); * * const customBuilder = <TParams extends { name: string }>(params: TParams) => { * const field = customBigInt.new(params); * return field._setNewBuilderMethods({ * test: <TTest extends { age: number }>(param: TTest) => * // This will union the type `string` with what already exists in the field 'create' type * field._setPartialAttributes<{ create: string }, { create: 'union' }>(param) * }); * }; * * // Then your user can use it like: * * const field = customBuilder({ name: 'test' }).test({ age: 2 }); * ``` * * **Important**: `customBuilder` will be used by the end user and you are responsible for documenting it. */ _setNewBuilderMethods<const TFunctions extends InstanceType<any>>(functions?: TFunctions): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes> & TFunctions; /** * FOR LIBRARY MAINTAINERS ONLY * * Focused for library maintainers that want to support a custom field type not supported by palmares. * This let's them partially update the custom attributes of the field. By default setCustomAttributes * will override the custom attributes entirely. */ _setPartialAttributes<TNewType extends { create?: any; read?: any; update?: any; }, TActions extends { create?: 'merge' | 'union' | 'replace'; read?: 'merge' | 'union' | 'replace'; update?: 'merge' | 'union' | 'replace'; }, TNewAllowedQueryOperations extends FieldWithOperationTypeForSearch<TActions['read'] extends 'merge' ? TType['read'] & TNewType['read'] : TActions['read'] extends 'union' ? TType['read'] | TNewType['read'] : TActions['read'] extends 'replace' ? TNewType['read'] : TType['read']> = Pick<FieldWithOperationTypeForSearch<TActions['read'] extends 'merge' ? TType['read'] & TNewType['read'] : TActions['read'] extends 'union' ? TType['read'] | TNewType['read'] : TActions['read'] extends 'replace' ? TNewType['read'] : TType['read']>, 'like' | 'and' | 'in' | 'or' | 'eq' | 'is'>>(): <const TCustomPartialAttributes>(partialCustomAttributes: TCustomPartialAttributes) => CharField<{ create: TActions['create'] extends 'merge' ? TType['create'] & TNewType['create'] : TActions['create'] extends 'union' ? TType['create'] | TNewType['create'] : TActions['create'] extends 'replace' ? TNewType['create'] : TType['create']; read: TActions['read'] extends 'merge' ? TType['read'] & TNewType['read'] : TActions['read'] extends 'union' ? TType['read'] | TNewType['read'] : TActions['read'] extends 'replace' ? TNewType['read'] : TType['read']; update: TActions['update'] extends 'merge' ? TType['update'] & TNewType['update'] : TActions['update'] extends 'union' ? TType['update'] | TNewType['update'] : TActions['update'] extends 'replace' ? TNewType['update'] : TType['update']; }, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes'] & TCustomPartialAttributes; }, TNewAllowedQueryOperations>; setCustomAttributes<const TCustomAttributes extends Parameters<TDefinitions['engineInstance']['fields']['charFieldParser']['translate']>[0]['customAttributes']>(customAttributes: TCustomAttributes): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TCustomAttributes; }, TFieldOperationTypes>; unique<TUnique extends boolean = true>(isUnique?: TUnique): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TUnique extends false ? false : true; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; allowNull<TNull extends boolean = true>(isNull?: TNull): CharField<{ create: TType['create'] | null | undefined; read: TType['read'] | null | undefined; update: TType['update'] | null | undefined; }, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TNull extends false ? false : true; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, Pick<FieldWithOperationTypeForSearch<TType['read'] | null>, 'like' | 'and' | 'in' | 'or' | 'eq' | 'is'>>; allowBlank<TBlank extends boolean = true>(isBlank?: TBlank): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; allowBlank: TBlank extends false ? false : true; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; /** * This method is used to create an index on the database for this field. */ dbIndex<TDbIndex extends boolean = true>(isDbIndex?: TDbIndex): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDbIndex extends false ? false : true; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; underscored<TUnderscored extends boolean = true>(isUnderscored?: TUnderscored): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TUnderscored extends false ? false : true; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; primaryKey<TIsPrimaryKey extends boolean = true>(isPrimaryKey?: TIsPrimaryKey): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TIsPrimaryKey extends false ? false : true; auto: TDefinitions['auto']; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; auto<TIsAuto extends boolean = true>(isAuto?: TIsAuto): CharField<{ create: TType['create'] | undefined; read: TType['read']; update: TType['update'] | undefined; }, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TIsAuto extends false ? false : true; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; default<TDefault extends TType['create']>(defaultValue: TDefault): CharField<{ create: TType['create'] | TDefault | null | undefined; read: TType['read']; update: TType['update'] | null | undefined; }, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; hasDefaultValue: true; defaultValue: TDefault; databaseName: TDefinitions['databaseName']; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; databaseName<TDatabaseName extends string>(databaseName: TDatabaseName): CharField<TType, { [TKey in Exclude<keyof TDefinitions, 'underscored' | 'allowNull' | 'dbIndex' | 'unique' | 'isPrimaryKey' | 'auto' | 'defaultValue' | 'databaseName' | 'typeName' | 'engineInstance' | 'customAttributes'>]: TDefinitions[TKey]; } & { unique: TDefinitions['unique']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; underscored: TDefinitions['underscored']; isPrimaryKey: TDefinitions['isPrimaryKey']; auto: TDefinitions['auto']; hasDefaultValue: TDefinitions['hasDefaultValue']; defaultValue: TDefinitions['defaultValue']; databaseName: TDatabaseName; typeName: TDefinitions['typeName']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; }, TFieldOperationTypes>; /** * This method can be used to override the type of a field. This is useful for library * maintainers that want to support a custom field type not supported by palmares. * * ### Note * - Your library should provide documentation of the fields that are supported. * - This should be used alongside the `_setPartialAttributes` method and `_setNewBuilderMethods`. * Instead of making users type NameOfYourField.new(), you should create a function that calls .new and creates * a new instance of the field for them. * - TDefinitions exists on type-level only, in runtime, it's not a guarantee of nothing. If TDefinitions * sets unique to true, it's up to you to do `NameOfYourField.new().unique()`, because otherwise it will be false */ static _overrideType<const TNewType extends { create: any; update: any; read: any; }, const TDefinitions extends { customAttributes: any; unique: boolean; auto: boolean; allowNull: boolean; dbIndex: boolean; isPrimaryKey: boolean; defaultValue: any; typeName: string; hasDefaultValue: boolean; engineInstance: DatabaseAdapter; allowBlank: boolean; }, const TFieldOperationTypes extends FieldWithOperationTypeForSearch<any> | Pick<FieldWithOperationTypeForSearch<any>, any>>(args: { typeName: string; toStringCallback?: ToStringCallback; compareCallback?: CompareCallback; optionsCallback?: OptionsCallback; newInstanceCallback?: NewInstanceArgumentsCallback; allowedQueryOperations?: (keyof TFieldOperationTypes)[]; customImports?: CustomImportsForFieldType[]; }): TDefinitions['customAttributes'] extends undefined ? { new: <const TMaxCharLength extends number>(params: { maxLen: TMaxCharLength; }) => CharField<TNewType, { unique: TDefinitions['unique']; auto: TDefinitions['auto']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; isPrimaryKey: TDefinitions['isPrimaryKey']; defaultValue: TDefinitions['defaultValue']; underscored: boolean; databaseName: string | undefined; hasDefaultValue: TDefinitions['hasDefaultValue']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; typeName: TDefinitions['typeName']; allowBlank: TDefinitions['allowBlank']; maxLength: TMaxCharLength; }, TFieldOperationTypes>; } : { new: <const TMaxCharLength extends number>(params: { maxLen: TMaxCharLength; } & TDefinitions['customAttributes']) => CharField<TNewType, { unique: TDefinitions['unique']; auto: TDefinitions['auto']; allowNull: TDefinitions['allowNull']; dbIndex: TDefinitions['dbIndex']; isPrimaryKey: TDefinitions['isPrimaryKey']; defaultValue: TDefinitions['defaultValue']; underscored: boolean; databaseName: string | undefined; hasDefaultValue: TDefinitions['hasDefaultValue']; engineInstance: TDefinitions['engineInstance']; customAttributes: TDefinitions['customAttributes']; typeName: TDefinitions['typeName']; allowBlank: TDefinitions['allowBlank']; maxLength: TMaxCharLength; }, TFieldOperationTypes>; }; static new<const TMaxCharLength extends number>(args: { maxLen: TMaxCharLength; }): CharField<{ create: string; read: string; update: string; }, { unique: false; allowNull: false; dbIndex: false; underscored: true; allowBlank: true; isPrimaryKey: false; auto: false; defaultValue: undefined; typeName: string; hasDefaultValue: false; databaseName: undefined; engineInstance: DatabaseAdapter; customAttributes: any; maxLength: TMaxCharLength; }, Pick<FieldWithOperationTypeForSearch<string>, 'like' | 'and' | 'in' | 'or' | 'eq' | 'is'>>; } //# sourceMappingURL=char.d.ts.map