From 95efb868b8aa553971c4e38ca92e395f5a338193 Mon Sep 17 00:00:00 2001 From: Rohit Kadhe <113367036+rohit-kadhe@users.noreply.github.com> Date: Wed, 27 Mar 2024 15:45:34 -0600 Subject: [PATCH] document functions and classes (#10) --- core/clickhouse_schema.ts | 17 +++++++- data_types/ch_array.ts | 4 ++ data_types/ch_boolean.ts | 3 ++ data_types/ch_date.ts | 14 +++++++ data_types/ch_decimal.ts | 5 +++ data_types/ch_float.ts | 7 +++- data_types/ch_integer.ts | 37 ++++++++++++++++++ data_types/ch_json.ts | 3 ++ data_types/ch_low_ cardinality.ts | 7 ++++ data_types/ch_nullable.ts | 4 ++ data_types/ch_string.ts | 7 ++++ data_types/ch_uuid.ts | 3 ++ data_types/index.ts | 64 ++++++++++++++++++++++++++----- utils/util.ts | 1 + 14 files changed, 164 insertions(+), 12 deletions(-) diff --git a/core/clickhouse_schema.ts b/core/clickhouse_schema.ts index 61b1fb7..73fc2a6 100644 --- a/core/clickhouse_schema.ts +++ b/core/clickhouse_schema.ts @@ -23,13 +23,20 @@ export interface ChSchemaOptions { additional_options?: string[] } +/** + * IClickhouseSchema is an interface that represents a clickhouse schema. + */ interface IClickhouseSchema { GetOptions: () => ChSchemaOptions GetCreateTableQuery: () => string GetCreateTableQueryAsList: () => string[] } -/* This class is used to represent a clickhouse table schema */ +/** + * ClickhouseSchema is a class that represents a clickhouse schema. + * @param schema is the schema definition + * @param options is the options for the schema + */ export class ClickhouseSchema implements IClickhouseSchema { readonly schema: SchemaDefinition private readonly options: ChSchemaOptions @@ -75,10 +82,18 @@ export class ClickhouseSchema imple return createTableQuery } + /** + * + * @returns the create table query as a list of strings + */ GetCreateTableQueryAsList (): string[] { return this.GetCreateTableQuery().split('\n') } + /** + * + * @returns the create table query as a string + */ toString (): string { return this.GetCreateTableQuery() } diff --git a/data_types/ch_array.ts b/data_types/ch_array.ts index 5b216f0..273fcef 100644 --- a/data_types/ch_array.ts +++ b/data_types/ch_array.ts @@ -1,5 +1,9 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChArray is a class that represents an array of a Clickhouse data type + * @param T - The type of the array elements (can be a ChDataType or another ChArray) + */ export class ChArray> implements ChDataType { readonly innerType: T readonly typeStr: string diff --git a/data_types/ch_boolean.ts b/data_types/ch_boolean.ts index 827f72f..42782dc 100644 --- a/data_types/ch_boolean.ts +++ b/data_types/ch_boolean.ts @@ -1,5 +1,8 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChBoolean is a class that represents a Clickhouse Boolean data type + */ export class ChBoolean implements ChDataType { readonly typeStr: 'Boolean' = 'Boolean' as const diff --git a/data_types/ch_date.ts b/data_types/ch_date.ts index 239b535..ce4ba34 100644 --- a/data_types/ch_date.ts +++ b/data_types/ch_date.ts @@ -1,5 +1,8 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChDate is a class that represents a Clickhouse Date data type + */ export class ChDate implements ChDataType { readonly typeStr: 'Date' = 'Date' as const @@ -8,6 +11,9 @@ export class ChDate implements ChDataType { } } +/** + * ChDate32 is a class that represents a Clickhouse Date32 data type + */ export class ChDate32 implements ChDataType { readonly typeStr: 'Date32' = 'Date32' as const @@ -16,6 +22,9 @@ export class ChDate32 implements ChDataType { } } +/** + * ChDate64 is a class that represents a Clickhouse Date64 data type + */ export class ChDateTime implements ChDataType { readonly typeStr: `DateTime('${T}')` @@ -28,6 +37,11 @@ export class ChDateTime implements ChDataType { } } +/** + * ChDateTime64 is a class that represents a Clickhouse DateTime64 data type + * @param T - The precision of the DateTime64 + * @param V - The timezone of the DateTime64 + */ export class ChDateTime64 implements ChDataType { readonly typeStr: `DateTime64(${T}, '${V}')` diff --git a/data_types/ch_decimal.ts b/data_types/ch_decimal.ts index 06a839b..8be2bbd 100644 --- a/data_types/ch_decimal.ts +++ b/data_types/ch_decimal.ts @@ -1,5 +1,10 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChDecimal is a class that represents a Clickhouse Decimal data type + * @param P - The precision of the Decimal + * @param S - The scale of the Decimal + */ export class ChDecimal

implements ChDataType { readonly typeStr: `Decimal(${P},${S})` diff --git a/data_types/ch_float.ts b/data_types/ch_float.ts index f18358b..ae8d3f4 100644 --- a/data_types/ch_float.ts +++ b/data_types/ch_float.ts @@ -1,5 +1,8 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChFloat32 is a class that represents a Clickhouse Float32 data type + */ export class ChFloat32 implements ChDataType { readonly typeStr: 'Float32' = 'Float32' as const @@ -7,7 +10,9 @@ export class ChFloat32 implements ChDataType { return this.typeStr } } - +/** + * ChFloat64 is a class that represents a Clickhouse Float64 data type + */ export class ChFloat64 implements ChDataType { readonly typeStr: 'Float64' = 'Float64' as const diff --git a/data_types/ch_integer.ts b/data_types/ch_integer.ts index dee60a3..ed4baff 100644 --- a/data_types/ch_integer.ts +++ b/data_types/ch_integer.ts @@ -1,5 +1,8 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChUInt8 is a class that represents a Clickhouse UInt8 data type + */ export class ChUInt8 implements ChDataType { readonly typeStr: 'UInt8' = 'UInt8' as const @@ -12,6 +15,9 @@ export class ChUInt8 implements ChDataType { } } +/** + * ChUInt16 is a class that represents a Clickhouse UInt16 data type + */ export class ChUInt16 implements ChDataType { readonly typeStr: 'UInt16' = 'UInt16' as const @@ -24,6 +30,9 @@ export class ChUInt16 implements ChDataType { } } +/** + * ChUInt32 is a class that represents a Clickhouse UInt32 data type + */ export class ChUInt32 implements ChDataType { readonly typeStr: 'UInt32' = 'UInt32' as const @@ -32,6 +41,9 @@ export class ChUInt32 implements ChDataType { } } +/** + * ChUInt64 is a class that represents a Clickhouse UInt64 data type + */ export class ChUInt64 implements ChDataType { readonly typeStr: 'UInt64' = 'UInt64' as const @@ -40,6 +52,9 @@ export class ChUInt64 implements ChDataType { } } +/** + * ChUInt128 is a class that represents a Clickhouse UInt128 data type + */ export class ChUInt128 implements ChDataType { readonly typeStr: 'UInt128' = 'UInt128' as const @@ -48,6 +63,9 @@ export class ChUInt128 implements ChDataType { } } +/** + * ChUInt256 is a class that represents a Clickhouse UInt256 data type + */ export class ChUInt256 implements ChDataType { readonly typeStr: 'UInt256' = 'UInt256' as const @@ -56,6 +74,9 @@ export class ChUInt256 implements ChDataType { } } +/** + * ChInt8 is a class that represents a Clickhouse Int8 data type + */ export class ChInt8 implements ChDataType { readonly typeStr: 'Int8' = 'Int8' as const @@ -64,6 +85,10 @@ export class ChInt8 implements ChDataType { } } +/** + * ChInt16 is a class that represents a Clickhouse Int16 data type + + */ export class ChInt16 implements ChDataType { readonly typeStr: 'Int16' = 'Int16' as const @@ -72,6 +97,9 @@ export class ChInt16 implements ChDataType { } } +/** + * ChInt32 is a class that represents a Clickhouse Int32 data type + */ export class ChInt32 implements ChDataType { readonly typeStr: 'Int32' = 'Int32' as const @@ -80,6 +108,9 @@ export class ChInt32 implements ChDataType { } } +/** + * ChInt64 is a class that represents a Clickhouse Int64 data type + */ export class ChInt64 implements ChDataType { readonly typeStr: 'Int64' = 'Int64' as const @@ -88,6 +119,9 @@ export class ChInt64 implements ChDataType { } } +/** + * ChInt128 is a class that represents a Clickhouse Int128 data type + */ export class ChInt128 implements ChDataType { readonly typeStr: 'Int128' = 'Int128' as const @@ -96,6 +130,9 @@ export class ChInt128 implements ChDataType { } } +/** + * ChInt256 is a class that represents a Clickhouse Int256 data type + */ export class ChInt256 implements ChDataType { readonly typeStr: 'Int256' = 'Int256' as const diff --git a/data_types/ch_json.ts b/data_types/ch_json.ts index 85f0721..f9978f7 100644 --- a/data_types/ch_json.ts +++ b/data_types/ch_json.ts @@ -1,6 +1,9 @@ import { type ChSchemaDefinition } from '@clickhouse-schema-core/clickhouse_schema' import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChJSON is a class that represents a Clickhouse JSON data type + */ export class ChJSON implements ChDataType { readonly typeStr: 'JSON' readonly innerType: T diff --git a/data_types/ch_low_ cardinality.ts b/data_types/ch_low_ cardinality.ts index 6a30790..61a7cf7 100644 --- a/data_types/ch_low_ cardinality.ts +++ b/data_types/ch_low_ cardinality.ts @@ -1,5 +1,9 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChEnum is a class that represents a Clickhouse Enum data type + * @param T - The enum object. The keys are the enum names and the values are the enum values + */ export class ChEnum> implements ChDataType { readonly typeStr: string readonly innerType: T @@ -14,6 +18,9 @@ export class ChEnum> implements ChDataType { } } +/** + * ChLowCardinality is a class that represents a Clickhouse LowCardinality data type + */ export class ChLowCardinality implements ChDataType { readonly typeStr diff --git a/data_types/ch_nullable.ts b/data_types/ch_nullable.ts index 0359275..e795a43 100644 --- a/data_types/ch_nullable.ts +++ b/data_types/ch_nullable.ts @@ -1,5 +1,9 @@ import { type ChPrimitiveType, type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChNullable is a class that represents a Clickhouse Nullable data type + * @param T - The inner type of the Nullable. Must be a primitive type + */ export class ChNullable implements ChDataType { readonly typeStr readonly innerType: T diff --git a/data_types/ch_string.ts b/data_types/ch_string.ts index 2781f09..398937b 100644 --- a/data_types/ch_string.ts +++ b/data_types/ch_string.ts @@ -1,5 +1,8 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChString is a class that represents a Clickhouse String data type + */ export class ChString implements ChDataType { readonly typeStr: 'String' = 'String' as const @@ -8,6 +11,10 @@ export class ChString implements ChDataType { } } +/** + * ChFixedString is a class that represents a Clickhouse FixedString data type + * @param T - The length of the FixedString + */ export class ChFixedString implements ChDataType { readonly typeStr: `FixedString(${T})` diff --git a/data_types/ch_uuid.ts b/data_types/ch_uuid.ts index a6f0a8b..27101dc 100644 --- a/data_types/ch_uuid.ts +++ b/data_types/ch_uuid.ts @@ -1,5 +1,8 @@ import { type ChDataType } from '@clickhouse-schema-data-types/index' +/** + * ChUUID is a class that represents a Clickhouse UUID data type + */ export class ChUUID implements ChDataType { readonly typeStr: 'UUID' = 'UUID' as const diff --git a/data_types/index.ts b/data_types/index.ts index 0e7500f..d8f9316 100644 --- a/data_types/index.ts +++ b/data_types/index.ts @@ -11,12 +11,14 @@ import { ChUUID } from '@clickhouse-schema-data-types/ch_uuid' import { ChNullable } from '@clickhouse-schema-data-types/ch_nullable' import { ChDecimal } from '@clickhouse-schema-data-types/ch_decimal' +/** + * ChDataType is an interface that represents a Clickhouse data type + */ export interface ChDataType { typeStr: string toString: () => string } -// Individual type definitions // Integer types unsigned export const CHUInt8 = new ChUInt8() export const CHUInt16 = new ChUInt16() @@ -34,27 +36,69 @@ export const CHInt256 = new ChInt256() // Float types export const CHFloat32 = new ChFloat32() export const CHFloat64 = new ChFloat64() -// Decimal type -export const CHDecimal =

(precision: P, scale: S): ChDecimal => new ChDecimal(precision, scale) // Boolean type export const CHBoolean = new ChBoolean() -// String types export const CHString = new ChString() -export const CHFixedString = (length: T): ChFixedString => new ChFixedString(length) export const CHUUID = new ChUUID() -// Date types export const CHDate = new ChDate() export const CHDate32 = new ChDate32() +/** + * + * @param precision precision of the decimal + * @param scale scale of the decimal + * @returns a new ChDecimal object + */ +export const CHDecimal =

(precision: P, scale: S): ChDecimal => new ChDecimal(precision, scale) + +/** + * + * @param length length of the fixed string + * @returns a new ChFixedString object + */ +export const CHFixedString = (length: T): ChFixedString => new ChFixedString(length) + +/** + * + * @param timezone timezone of the DateTime + * @returns a new ChDateTime object + */ export const CHDateTime = (timezone: TZ): ChDateTime => new ChDateTime(timezone) +/** + * + * @param precision precision of the DateTime64 + * @param timezone timezone of the DateTime64 + * @returns a new ChDateTime64 object + */ export const CHDateTime64 =

(precision: P, timezone: TZ): ChDateTime64 => new ChDateTime64(precision, timezone) -// JSON type +/** + * + * @param schema schema definition for the JSON + * @returns a new ChJSON object + */ export const CHJSON = (schema: T): ChJSON => new ChJSON(schema) -// Array type +/** + * + * @param t type of the array + * @returns a new ChArray object + */ export const CHArray = (t: T): ChArray => new ChArray(t) -// Low cardinality types +/** + * + * @param enumObj enum object. The keys are the enum names and the values are the enum values + * @returns a new ChEnum object + */ export const CHEnum = >(enumObj: T): ChEnum => new ChEnum(enumObj) +/** + * + * @param type type of the low cardinality. Must be a string or fixed string + * @returns a new ChLowCardinality object + */ export const CHLowCardinality = >(type: T): ChLowCardinality => new ChLowCardinality(type) -// Nullable type +/** + * + * @param type type of the nullable. Must be a primitive type + * @returns a new ChNullable object + */ export const CHNullable = (type: T): ChNullable => new ChNullable(type) export const ClickhouseTypes = { diff --git a/utils/util.ts b/utils/util.ts index 8ab8c0d..1d59f9c 100644 --- a/utils/util.ts +++ b/utils/util.ts @@ -4,6 +4,7 @@ import { type MapChSchemaTypes } from '@clickhouse-schema-data-types/index' export type ExtractInnerType = T extends `${infer _BeforeBracket}(${infer Rest})` ? ExtractInnerType : T + export type ExtractOuterType = T extends `${infer BeforeBracket}(${infer _Rest})` ? BeforeBracket : T