diff --git a/NixSupport/haskell-packages/ihp-datasync-typescript.nix b/NixSupport/haskell-packages/ihp-datasync-typescript.nix new file mode 100644 index 000000000..84385b124 --- /dev/null +++ b/NixSupport/haskell-packages/ihp-datasync-typescript.nix @@ -0,0 +1,15 @@ +{ mkDerivation, ihp, ihp-ide, neat-interpolation, lib, with-utf8_1_1_0_0, megaparsec }: +mkDerivation { + pname = "ihp-datasync-typescript"; + version = "v1.3.0"; + src = ./../../ihp-datasync-typescript; + libraryHaskellDepends = [ + ihp ihp-ide neat-interpolation + ]; + testHaskellDepends = [ + ihp ihp-ide neat-interpolation megaparsec + ]; + executableHaskellDepends = [ ihp with-utf8_1_1_0_0 ]; + description = "TypeScript code generation for IHP DataSync"; + license = lib.licenses.mit; +} \ No newline at end of file diff --git a/devenv-module.nix b/devenv-module.nix index 737af7554..1205c97dd 100644 --- a/devenv-module.nix +++ b/devenv-module.nix @@ -119,6 +119,7 @@ that is defined in flake-module.nix ide = ghcCompiler.ihp-ide; ssc = ghcCompiler.ihp-ssc; migrate = ghcCompiler.ihp-migrate; + datasync-typescript = ghcCompiler.ihp-datasync-typescript; }; }; } diff --git a/ihp-datasync-typescript/IHP/DataSync/TypeScript/Compiler.hs b/ihp-datasync-typescript/IHP/DataSync/TypeScript/Compiler.hs new file mode 100644 index 000000000..33973f1b0 --- /dev/null +++ b/ihp-datasync-typescript/IHP/DataSync/TypeScript/Compiler.hs @@ -0,0 +1,472 @@ +module IHP.DataSync.TypeScript.Compiler where + +import IHP.Prelude +import IHP.IDE.SchemaDesigner.Types +import NeatInterpolation + +generateTypeScriptTypeDefinitions :: [Statement] -> Text +generateTypeScriptTypeDefinitions schema = [trimming| +declare module 'ihp-datasync' { + ${tableNameTypeDef} + ${tableNameToRecordType} + ${enumTypes} + ${recordInterfaces} + ${newRecordInterfaces} + ${newRecordType'} + + type UUID = string; + + class ConditionBuildable> { + conditionBuildableType: table; + + where>(column: column, value: IHPRecord
[column]): T; + where(conditionBuilder: ConditionBuilder
): T; + where(filterRecord: Partial>): T; + filterWhere>(column: column, value: IHPRecord
[column]): T; + whereNot>(column: column, value: IHPRecord
[column]): T; + whereLessThan>(column: column, value: IHPRecord
[column]): T; + whereLessThanOrEqual>(column: column, value: IHPRecord
[column]): T; + whereGreaterThan>(column: column, value: IHPRecord
[column]): T; + whereGreaterThanOrEqual>(column: column, value: IHPRecord
[column]): T; + + or (...conditionBuilder: ConditionBuilder
[]): T; + and(...conditionBuilder: ConditionBuilder
[]): T; + + whereIn>(column: column, value: Array[column]>): T; + } + + class ConditionBuilder
extends ConditionBuildable> {} + + function or
( conditions: ConditionBuilder
[]): ConditionBuilder
; + function or
(...conditions: ConditionBuilder
[]): ConditionBuilder
; + function and
( conditions: ConditionBuilder
[]): ConditionBuilder
; + function and
(...conditions: ConditionBuilder
[]): ConditionBuilder
; + + class QueryBuilder
extends ConditionBuildable> { + query: Query; + + select>(columns: column[]): QueryBuilder ? {} : result) & Pick, column>>; + select>(...columns: column[]): QueryBuilder ? {} : result) & Pick, column>>; + + whereTextSearchStartsWith, value extends IHPRecord
[column] & string>(column: column, value: value): QueryBuilder; + + orderBy(column: keyof IHPRecord
): QueryBuilder; + orderByAsc(column: keyof IHPRecord
): QueryBuilder; + orderByDesc(column: keyof IHPRecord
): QueryBuilder; + limit(limit: number): QueryBuilder; + offset(limit: number): QueryBuilder; + + fetch(): Promise>; + fetchOne(): Promise; + subscribe(subscribe: (value: Array) => void): (() => void); + } + + ${conditionBuilderConstructors} + + interface Query
{ + table: table; + } + + /** + * Returns a new database query builder. + * + * @example + * const tasks = await query('tasks') + * .orderBy('createdAt') + * .limit(10) + * .fetch(); + * + * @param {string} table The name of one of your project's table. + */ + function query
(table: table): QueryBuilder>; + function query
>(table: table, columns: column[]): QueryBuilder, column>>; + + class DataSubscription
{ + isClosed: boolean; + isConnected: boolean; + + constructor(query: Query); + createOnServer(): Promise; + close(): Promise; + closeIfNotUsed(): Promise; + getRecords(): Array; + subscribe(subscribe: (value: Array) => void): (() => void); + } + + ${initThinBackendTypeDef'} + + /** + * Creates a row inside a database table. Returns a promise of the newly created object. + * + * @example + * const task = await createRecord('tasks', { + * title: 'Hello World', + * userId: getCurrentUserId() + * }) + * @param {string} tableName The name of one of your project's table. + * @param {object} record An object representing the row to be inserted. Columns with a database-side default value don't need to be specified. + * @see {@link createRecords} You can use `createRecords` to batch insert multiple records in an efficient way + */ + function createRecord
(tableName: table, record: NewRecord>): Promise>; + + /** + * Updates a row inside a database table. Returns a promise of the updated row. + * + * @example + * updateRecord('tasks', task.id, { + * isCompleted: true + * }) + * @param {string} tableName The name of one of your project's table + * @param {UUID} id The id of the row to be updated + * @param {object} patch An patch object representing the changed values. + */ + function updateRecord
(tableName: table, id: UUID, patch: Partial>>): Promise>; + + /** + * Updates multiple rows inside a database table. Returns a promise of the updated rows. + * + * @example + * const taskIds = tasks.map(taks => task.id); + * updateRecords('tasks', taskIds, { + * isCompleted: true + * }) + * @param {string} tableName The name of one of your project's table + * @param {Array} ids The ids of the rows to be updated + * @param {object} patch An patch object representing the changed values. + */ + function updateRecords
(tableName: table, ids: Array, patch: Partial>>): Promise>>; + + /** + * Deletes a row inside a database table. + * + * @example + * deleteRecord('tasks', task.id) + * @param {string} tableName The name of one of your project's table + * @param {UUID} id The id of the row to be deleted + */ + function deleteRecord
(tableName: table, id: UUID): Promise; + + /** + * Deletes multiple rows inside a database table. + * + * @example + * const taskIds = tasks.map(task => task.id) + * deleteRecords('tasks', taskIds) + * @param {string} tableName The name of one of your project's table + * @param {Array} ids The ids of the rows to be deleted + */ + function deleteRecords
(tableName: table, ids: Array): Promise; + + /** + * Creates multiple rows inside a database table in a single INSERT query. Returns a promise of the newly created objects. + * + * @example + * const tasksToCreate = []; + * + * // Make 10 task objects, but don't insert them to the DB yet + * for (let i = 0; i < 10; i++) { + * tasksToCreate.push({ + * title: `Task $${i}`, + * userId: getCurrentUserId() + * }); + * } + * + * // Insert the 10 tasks + * const tasks = await createRecords('tasks', tasksToCreate) + * @param {string} tableName The name of one of your project's table. + * @param {object} records An array representing the rows to be inserted. + */ + function createRecords
(tableName: table, records: Array>>): Promise>>; + + function getCurrentUserId(): string; + function getCurrentUser(): Promise; + + interface LogoutOptions { + redirect?: string; + } + + function logout(options?: LogoutOptions): Promise; + + /** + * Useful to implement a login button. Redirects the user to the login page. + * + * The returned promise never resolves, as the browser is redirected to a different page. + * + * @example + * import { loginWithRedirect } from 'ihp-datasync'; + * function LoginButton() { + * const isLoading = useState(false); + * + * const doLogin = async () => { + * setLoading(true); + * await loginWithRedirect(); + * setLoading(false); + * } + * + * return + * } + */ + function loginWithRedirect(): Promise; + function ensureIsUser(): Promise; + function initAuth(): Promise; + + class Transaction { + public transactionId: UUID | null; + + start(): Promise; + commit(): Promise; + rollback(): Promise; + + query
(table: table): QueryBuilder>; + query
>(table: table, columns: column[]): QueryBuilder, column>>; + + createRecord
(tableName: table, record: NewRecord>): Promise>; + createRecords
(tableName: table, records: Array>>): Promise>>; + updateRecord
(tableName: table, id: UUID, patch: Partial>>): Promise>; + updateRecords
(tableName: table, ids: Array, patch: Partial>>): Promise>>; + deleteRecord
(tableName: table, id: UUID): Promise; + deleteRecords
(tableName: table, ids: Array): Promise; + } + + function withTransaction(callback: ((transaction: Transaction) => Promise) ): Promise; + + const enum NewRecordBehaviour { + APPEND_NEW_RECORD = 0, + PREPEND_NEW_RECORD = 1 + } + interface DataSubscriptionOptions { + /** When you add a new record, you might want the new record to be always displayed at the start of the list for UX reasons, ignoring any sort behaviour specified in the order by of the database query. */ + newRecordBehaviour: NewRecordBehaviour; + } +} + +declare module 'ihp-datasync/react' { + import { TableName, QueryBuilder, User, DataSubscriptionOptions } from 'ihp-datasync'; + + /** + * React hook for querying the database and streaming results in real-time + * + * @example + * function TasksList() { + * const tasks = useQuery(query('tasks').orderBy('createdAt')) + * + * return
+ * {tasks.map(task =>
{task.title}
)} + *
+ * } + * + * @param {QueryBuilder} queryBuilder A database query + */ + function useQuery
(queryBuilder: QueryBuilder, options?: DataSubscriptionOptions): Array | null; + + /** + * A version of `useQuery` when you only want to fetch a single record. + * + * Automatically adds a `.limit(1)` to the query and returns the single result instead of a list. + * + * @example + * const message = useQuerySingleresult(query('messages').filterWhere('id', '1f290b39-c6d1-4dff-8404-0581f470253c')); + */ + function useQuerySingleResult
(queryBuilder: QueryBuilder): result | null; + + function useCurrentUser(): User | null; + + /** + * Returns true if there's a user logged in. Returns false if there's no logged in user. Returns null if loading. + * + * @example + * const isLoggedIn = useIsLoggedIn(); + */ + function useIsLoggedIn(): boolean | null; + + /** + * Returns true if the frontend is online and connected to the server. Returns false if the internet connection is offline and not connected to the server. + * + * @example + * const isConnected = useIsConnected(); + */ + function useIsConnected(): boolean; + + interface ThinBackendProps { + requireLogin?: boolean; + children: JSX.Element[] | JSX.Element; + } + function ThinBackend(props: ThinBackendProps): JSX.Element; +} + +declare module 'ihp-datasync/react18' { + import { TableName, QueryBuilder } from 'ihp-datasync'; + + /** + * React hook for querying the database and streaming results in real-time. + * + * Suspends while the data is being fetched from the server. + * + * @example + * function TasksList() { + * const tasks = useQuery(query('tasks').orderBy('createdAt')) + * + * return
+ * {tasks.map(task =>
{task.title}
)} + *
+ * } + * + * @param {QueryBuilder} queryBuilder A database query + */ + function useQuery
(queryBuilder: QueryBuilder): Array; +} +|] + where + tableNameTypeDef :: Text + tableNameTypeDef = "type TableName = " <> (tableNames |> map tshow |> intercalate " | " ) <> ";" + + tableNames :: [Text] + tableNames = createTableStatements |> map (get #name) + + createTableStatements :: [CreateTable] + createTableStatements = + schema |> mapMaybe \case + StatementCreateTable { unsafeGetCreateTable = table } -> Just table + otherwise -> Nothing + + recordInterfaces :: Text + recordInterfaces = createTableStatements + |> map recordInterface + |> intercalate "\n" + + newRecordInterfaces :: Text + newRecordInterfaces = createTableStatements + |> map newRecordInterface + |> intercalate "\n" + + enumTypes :: Text + enumTypes = + schema + |> mapMaybe \case + CreateEnumType { name, values } -> Just (generateEnumType name values) + otherwise -> Nothing + |> intercalate "\n" + + tableNameToRecordType :: Text + tableNameToRecordType = [trimming| + type IHPRecord
= ${implementation}; + |] + where + -- table extends "users" ? UserRecord : (table extends "tasks" ? TaskRecord : never) + implementation = gen createTableStatements + + gen [] = "never" + gen (table:rest) = "table extends " <> tshow (get #name table) <> " ? " <> tableNameToModelName (get #name table) <> " : (" <> gen rest <> ")" + + newRecordType' :: Text + newRecordType' = newRecordType createTableStatements + + initThinBackendTypeDef' :: Text + initThinBackendTypeDef' = initThinBackendTypeDef + + conditionBuilderConstructors :: Text + conditionBuilderConstructors = tableNames + |> map forTable + |> intercalate "\n" + where + forTable tableName = [trimming|function where(conditionBuilder: ConditionBuilder<'${tableName}'>): ConditionBuilder<'${tableName}'>; +function where(filterRecord: Partial<${record}>) : ConditionBuilder<'${tableName}'>; +function where (column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>; +function filterWhere (column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>; +function eq (column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>; +function notEq (column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>; +function lessThan (column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>; +function lessThanOrEqual (column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>; +function greaterThan (column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>; +function greaterThanOrEqual(column: column, value: ${record}[column]): ConditionBuilder<'${tableName}'>;|] + where + record = tableNameToModelName tableName + +recordInterface :: CreateTable -> Text +recordInterface CreateTable { name, columns } = "interface " <> tableNameToModelName name <> " {\n" <> fields <> "\n}" + where + fields = columns + |> map columnToField + |> intercalate "\n" + columnToField Column { name, columnType, notNull } = " " <> columnNameToFieldName name <> ": " <> columnTypeToTypeScript columnType notNull <> ";" + +-- | Generates a record interface where fields with default values are optional +newRecordInterface :: CreateTable -> Text +newRecordInterface CreateTable { name, columns } = [trimming| + /** + * ${description} + */ + interface New${modelName} { + ${fields} + } + |] + where + fields = columns + |> map columnToField + |> intercalate "\n" + columnToField Column { name, columnType, notNull, defaultValue } = columnNameToFieldName name <> (if isJust defaultValue then "?" else "") <> ": " <> columnTypeToTypeScript columnType notNull <> ";" + + modelName :: Text + modelName = tableNameToModelName name + + description :: Text + description = "A " <> modelName <> " object not yet inserted into the `" <> name <> "` table" + +columnTypeToTypeScript :: PostgresType -> Bool -> Text +columnTypeToTypeScript sqlType notNull = + if notNull + then columnTypeToTypeScript' sqlType + else columnTypeToTypeScript' sqlType <> " | null" + +columnTypeToTypeScript' :: PostgresType -> Text +columnTypeToTypeScript' PText = "string" +columnTypeToTypeScript' PInt = "number" +columnTypeToTypeScript' PSmallInt = "number" +columnTypeToTypeScript' PDouble = "number" +columnTypeToTypeScript' PBoolean = "boolean" +columnTypeToTypeScript' PUUID = "UUID" +columnTypeToTypeScript' (PCustomType customType) = tableNameToModelName customType +columnTypeToTypeScript' (PArray inner) = "Array<" <> columnTypeToTypeScript' inner <> ">" +columnTypeToTypeScript' otherwise = "string" + +newRecordType :: [CreateTable] -> Text +newRecordType createTableStatements = [trimming| + type NewRecord = ${implementation}; +|] + where + -- table extends "users" ? UserRecord : (table extends "tasks" ? TaskRecord : never) + implementation = gen createTableStatements + + gen [] = "never" + gen (table:rest) = "Type extends " <> tableNameToModelName (get #name table) <> " ? New" <> tableNameToModelName (get #name table) <> " : (" <> gen rest <> ")" + + +initThinBackendTypeDef :: Text +initThinBackendTypeDef = [trimming| + function initThinBackend(options: { host: string | undefined; }): void; +|] + + + +packageJsonContent :: Text +packageJsonContent = [trimming| +{ + "name": "@types/ihp-datasync", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + "types": "main.d.ts" +} +|] + +generateEnumType :: Text -> [Text] -> Text +generateEnumType _ [] = "" +generateEnumType name values = "type " <> tableNameToModelName name <> " = " <> (intercalate " | " (map compileValue values)) <> ";" + where + compileValue :: Text -> Text + compileValue value = "'" <> value <> "'" \ No newline at end of file diff --git a/ihp-datasync-typescript/README.md b/ihp-datasync-typescript/README.md new file mode 100644 index 000000000..3cfc08c18 --- /dev/null +++ b/ihp-datasync-typescript/README.md @@ -0,0 +1,37 @@ +# ihp-datasync-typescript + +1. Add `ihp-datasync-typescript` to `flake.nix` +2. Run `generate-datasync-types Application/Schema.sql Frontend/types/ihp-datasync/index.d.ts` + +Requires a `typeRoots` in `tsconfig.json` like this: + +```json +{ + "compilerOptions": { + "target": "es6", + "lib": [ + "dom", + "dom.iterable", + "esnext" + ], + "allowJs": true, + "skipLibCheck": true, + "esModuleInterop": true, + "allowSyntheticDefaultImports": true, + "strict": true, + "forceConsistentCasingInFileNames": true, + "noFallthroughCasesInSwitch": true, + "module": "esnext", + "moduleResolution": "node", + "resolveJsonModule": true, + "isolatedModules": true, + "noEmit": true, + "jsx": "react-jsx", + "typeRoots": ["./node_modules/@types", "./Frontend/types"], + "declaration": true, + }, + "include": [ + "src" + ] +} +``` \ No newline at end of file diff --git a/ihp-datasync-typescript/Test/Spec.hs b/ihp-datasync-typescript/Test/Spec.hs new file mode 100644 index 000000000..d08b06e52 --- /dev/null +++ b/ihp-datasync-typescript/Test/Spec.hs @@ -0,0 +1,476 @@ +module Main where + +import Test.Hspec +import IHP.Prelude +import IHP.DataSync.TypeScript.Compiler +import NeatInterpolation +import IHP.ControllerPrelude + +import qualified IHP.IDE.SchemaDesigner.Parser as Parser +import IHP.IDE.SchemaDesigner.Types +import qualified Text.Megaparsec as Megaparsec + +main :: IO () +main = hspec tests + +tests = do + describe "Test.Web.View.TypeDefinitions.TypeScript" do + describe "generateTypeScriptTypeDefinitions" do + it "should generate a valid typescript definition file" do + let schema = parseSqlStatements $ cs [plain| + CREATE TABLE users ( + id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL, + email TEXT NOT NULL, + password_hash TEXT NOT NULL, + locked_at TIMESTAMP WITH TIME ZONE DEFAULT NULL, + failed_login_attempts INT DEFAULT 0 NOT NULL, + access_token TEXT DEFAULT NULL + ); + CREATE TYPE colors AS ENUM ('red', 'blue'); + CREATE TABLE tasks ( + id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL, + title TEXT NOT NULL, + created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL, + user_id UUID NOT NULL, + color colors NOT NULL, + color_arr colors[] NOT NULL + ); + CREATE INDEX tasks_user_id_index ON tasks (user_id); + ALTER TABLE tasks ADD CONSTRAINT tasks_ref_user_id FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE NO ACTION; + CREATE POLICY "Users can manage their tasks" ON tasks USING (user_id = ihp_user_id()) WITH CHECK (user_id = ihp_user_id()); + ALTER TABLE tasks ENABLE ROW LEVEL SECURITY; + |] + let expected = [trimming| + declare module 'ihp-datasync' { + type TableName = "users" | "tasks"; + type IHPRecord
= table extends "users" ? User : (table extends "tasks" ? Task : (never)); + type Color = 'red' | 'blue'; + interface User { + id: UUID; + email: string; + passwordHash: string; + lockedAt: string | null; + failedLoginAttempts: number; + accessToken: string | null; + } + interface Task { + id: UUID; + title: string; + createdAt: string; + userId: UUID; + color: Color; + colorArr: Array; + } + /** + * A User object not yet inserted into the `users` table + */ + interface NewUser { + id?: UUID; + email: string; + passwordHash: string; + lockedAt?: string | null; + failedLoginAttempts?: number; + accessToken?: string | null; + } + /** + * A Task object not yet inserted into the `tasks` table + */ + interface NewTask { + id?: UUID; + title: string; + createdAt?: string; + userId: UUID; + color: Color; + colorArr: Array; + } + type NewRecord = Type extends User ? NewUser : (Type extends Task ? NewTask : (never)); + + type UUID = string; + + class ConditionBuildable
> { + conditionBuildableType: table; + + where>(column: column, value: IHPRecord
[column]): T; + where(conditionBuilder: ConditionBuilder
): T; + where(filterRecord: Partial>): T; + filterWhere>(column: column, value: IHPRecord
[column]): T; + whereNot>(column: column, value: IHPRecord
[column]): T; + whereLessThan>(column: column, value: IHPRecord
[column]): T; + whereLessThanOrEqual>(column: column, value: IHPRecord
[column]): T; + whereGreaterThan>(column: column, value: IHPRecord
[column]): T; + whereGreaterThanOrEqual>(column: column, value: IHPRecord
[column]): T; + + or (...conditionBuilder: ConditionBuilder
[]): T; + and(...conditionBuilder: ConditionBuilder
[]): T; + + whereIn>(column: column, value: Array[column]>): T; + } + + class ConditionBuilder
extends ConditionBuildable> {} + + function or
( conditions: ConditionBuilder
[]): ConditionBuilder
; + function or
(...conditions: ConditionBuilder
[]): ConditionBuilder
; + function and
( conditions: ConditionBuilder
[]): ConditionBuilder
; + function and
(...conditions: ConditionBuilder
[]): ConditionBuilder
; + + class QueryBuilder
extends ConditionBuildable> { + query: Query; + + select>(columns: column[]): QueryBuilder ? {} : result) & Pick, column>>; + select>(...columns: column[]): QueryBuilder ? {} : result) & Pick, column>>; + + whereTextSearchStartsWith, value extends IHPRecord
[column] & string>(column: column, value: value): QueryBuilder; + + orderBy(column: keyof IHPRecord
): QueryBuilder; + orderByAsc(column: keyof IHPRecord
): QueryBuilder; + orderByDesc(column: keyof IHPRecord
): QueryBuilder; + limit(limit: number): QueryBuilder; + offset(limit: number): QueryBuilder; + + fetch(): Promise>; + fetchOne(): Promise; + subscribe(subscribe: (value: Array) => void): (() => void); + } + + function where(conditionBuilder: ConditionBuilder<'users'>): ConditionBuilder<'users'>; + function where(filterRecord: Partial) : ConditionBuilder<'users'>; + function where (column: column, value: User[column]): ConditionBuilder<'users'>; + function filterWhere (column: column, value: User[column]): ConditionBuilder<'users'>; + function eq (column: column, value: User[column]): ConditionBuilder<'users'>; + function notEq (column: column, value: User[column]): ConditionBuilder<'users'>; + function lessThan (column: column, value: User[column]): ConditionBuilder<'users'>; + function lessThanOrEqual (column: column, value: User[column]): ConditionBuilder<'users'>; + function greaterThan (column: column, value: User[column]): ConditionBuilder<'users'>; + function greaterThanOrEqual(column: column, value: User[column]): ConditionBuilder<'users'>; + function where(conditionBuilder: ConditionBuilder<'tasks'>): ConditionBuilder<'tasks'>; + function where(filterRecord: Partial) : ConditionBuilder<'tasks'>; + function where (column: column, value: Task[column]): ConditionBuilder<'tasks'>; + function filterWhere (column: column, value: Task[column]): ConditionBuilder<'tasks'>; + function eq (column: column, value: Task[column]): ConditionBuilder<'tasks'>; + function notEq (column: column, value: Task[column]): ConditionBuilder<'tasks'>; + function lessThan (column: column, value: Task[column]): ConditionBuilder<'tasks'>; + function lessThanOrEqual (column: column, value: Task[column]): ConditionBuilder<'tasks'>; + function greaterThan (column: column, value: Task[column]): ConditionBuilder<'tasks'>; + function greaterThanOrEqual(column: column, value: Task[column]): ConditionBuilder<'tasks'>; + + interface Query
{ + table: table; + } + + /** + * Returns a new database query builder. + * + * @example + * const tasks = await query('tasks') + * .orderBy('createdAt') + * .limit(10) + * .fetch(); + * + * @param {string} table The name of one of your project's table. + */ + function query
(table: table): QueryBuilder>; + function query
>(table: table, columns: column[]): QueryBuilder, column>>; + + class DataSubscription
{ + isClosed: boolean; + isConnected: boolean; + + constructor(query: Query); + createOnServer(): Promise; + close(): Promise; + closeIfNotUsed(): Promise; + getRecords(): Array; + subscribe(subscribe: (value: Array) => void): (() => void); + } + + function initThinBackend(options: { host: string | undefined; }): void; + + /** + * Creates a row inside a database table. Returns a promise of the newly created object. + * + * @example + * const task = await createRecord('tasks', { + * title: 'Hello World', + * userId: getCurrentUserId() + * }) + * @param {string} tableName The name of one of your project's table. + * @param {object} record An object representing the row to be inserted. Columns with a database-side default value don't need to be specified. + * @see {@link createRecords} You can use `createRecords` to batch insert multiple records in an efficient way + */ + function createRecord
(tableName: table, record: NewRecord>): Promise>; + + /** + * Updates a row inside a database table. Returns a promise of the updated row. + * + * @example + * updateRecord('tasks', task.id, { + * isCompleted: true + * }) + * @param {string} tableName The name of one of your project's table + * @param {UUID} id The id of the row to be updated + * @param {object} patch An patch object representing the changed values. + */ + function updateRecord
(tableName: table, id: UUID, patch: Partial>>): Promise>; + + /** + * Updates multiple rows inside a database table. Returns a promise of the updated rows. + * + * @example + * const taskIds = tasks.map(taks => task.id); + * updateRecords('tasks', taskIds, { + * isCompleted: true + * }) + * @param {string} tableName The name of one of your project's table + * @param {Array} ids The ids of the rows to be updated + * @param {object} patch An patch object representing the changed values. + */ + function updateRecords
(tableName: table, ids: Array, patch: Partial>>): Promise>>; + + /** + * Deletes a row inside a database table. + * + * @example + * deleteRecord('tasks', task.id) + * @param {string} tableName The name of one of your project's table + * @param {UUID} id The id of the row to be deleted + */ + function deleteRecord
(tableName: table, id: UUID): Promise; + + /** + * Deletes multiple rows inside a database table. + * + * @example + * const taskIds = tasks.map(task => task.id) + * deleteRecords('tasks', taskIds) + * @param {string} tableName The name of one of your project's table + * @param {Array} ids The ids of the rows to be deleted + */ + function deleteRecords
(tableName: table, ids: Array): Promise; + + /** + * Creates multiple rows inside a database table in a single INSERT query. Returns a promise of the newly created objects. + * + * @example + * const tasksToCreate = []; + * + * // Make 10 task objects, but don't insert them to the DB yet + * for (let i = 0; i < 10; i++) { + * tasksToCreate.push({ + * title: `Task $${i}`, + * userId: getCurrentUserId() + * }); + * } + * + * // Insert the 10 tasks + * const tasks = await createRecords('tasks', tasksToCreate) + * @param {string} tableName The name of one of your project's table. + * @param {object} records An array representing the rows to be inserted. + */ + function createRecords
(tableName: table, records: Array>>): Promise>>; + + function getCurrentUserId(): string; + function getCurrentUser(): Promise; + + interface LogoutOptions { + redirect?: string; + } + + function logout(options?: LogoutOptions): Promise; + + /** + * Useful to implement a login button. Redirects the user to the login page. + * + * The returned promise never resolves, as the browser is redirected to a different page. + * + * @example + * import { loginWithRedirect } from 'ihp-datasync'; + * function LoginButton() { + * const isLoading = useState(false); + * + * const doLogin = async () => { + * setLoading(true); + * await loginWithRedirect(); + * setLoading(false); + * } + * + * return + * } + */ + function loginWithRedirect(): Promise; + function ensureIsUser(): Promise; + function initAuth(): Promise; + + class Transaction { + public transactionId: UUID | null; + + start(): Promise; + commit(): Promise; + rollback(): Promise; + + query
(table: table): QueryBuilder>; + query
>(table: table, columns: column[]): QueryBuilder, column>>; + + createRecord
(tableName: table, record: NewRecord>): Promise>; + createRecords
(tableName: table, records: Array>>): Promise>>; + updateRecord
(tableName: table, id: UUID, patch: Partial>>): Promise>; + updateRecords
(tableName: table, ids: Array, patch: Partial>>): Promise>>; + deleteRecord
(tableName: table, id: UUID): Promise; + deleteRecords
(tableName: table, ids: Array): Promise; + } + + function withTransaction(callback: ((transaction: Transaction) => Promise) ): Promise; + + const enum NewRecordBehaviour { + APPEND_NEW_RECORD = 0, + PREPEND_NEW_RECORD = 1 + } + interface DataSubscriptionOptions { + /** When you add a new record, you might want the new record to be always displayed at the start of the list for UX reasons, ignoring any sort behaviour specified in the order by of the database query. */ + newRecordBehaviour: NewRecordBehaviour; + } + } + + declare module 'ihp-datasync/react' { + import { TableName, QueryBuilder, User, DataSubscriptionOptions } from 'ihp-datasync'; + + /** + * React hook for querying the database and streaming results in real-time + * + * @example + * function TasksList() { + * const tasks = useQuery(query('tasks').orderBy('createdAt')) + * + * return
+ * {tasks.map(task =>
{task.title}
)} + *
+ * } + * + * @param {QueryBuilder} queryBuilder A database query + */ + function useQuery
(queryBuilder: QueryBuilder, options?: DataSubscriptionOptions): Array | null; + + /** + * A version of `useQuery` when you only want to fetch a single record. + * + * Automatically adds a `.limit(1)` to the query and returns the single result instead of a list. + * + * @example + * const message = useQuerySingleresult(query('messages').filterWhere('id', '1f290b39-c6d1-4dff-8404-0581f470253c')); + */ + function useQuerySingleResult
(queryBuilder: QueryBuilder): result | null; + + function useCurrentUser(): User | null; + + /** + * Returns true if there's a user logged in. Returns false if there's no logged in user. Returns null if loading. + * + * @example + * const isLoggedIn = useIsLoggedIn(); + */ + function useIsLoggedIn(): boolean | null; + + /** + * Returns true if the frontend is online and connected to the server. Returns false if the internet connection is offline and not connected to the server. + * + * @example + * const isConnected = useIsConnected(); + */ + function useIsConnected(): boolean; + + interface ThinBackendProps { + requireLogin?: boolean; + children: JSX.Element[] | JSX.Element; + } + function ThinBackend(props: ThinBackendProps): JSX.Element; + } + + declare module 'ihp-datasync/react18' { + import { TableName, QueryBuilder } from 'ihp-datasync'; + + /** + * React hook for querying the database and streaming results in real-time. + * + * Suspends while the data is being fetched from the server. + * + * @example + * function TasksList() { + * const tasks = useQuery(query('tasks').orderBy('createdAt')) + * + * return
+ * {tasks.map(task =>
{task.title}
)} + *
+ * } + * + * @param {QueryBuilder} queryBuilder A database query + */ + function useQuery
(queryBuilder: QueryBuilder): Array; + } + |] + + (generateTypeScriptTypeDefinitions schema) `shouldBe` expected + + describe "recordInterface" do + it "should generate required fields for fields with default values" do + let table = CreateTable + { name = "tasks" + , columns = + [ Column { name = "id", columnType = PUUID, defaultValue = Nothing, notNull = True, isUnique = False, generator = Nothing } + , Column { name = "title", columnType = PText, defaultValue = Just (TextExpression "untitled"), notNull = True, isUnique = False, generator = Nothing } + ] + , primaryKeyConstraint = PrimaryKeyConstraint ["id"] + , constraints = [] + , unlogged = False + } + let expected = [trimming| + interface Task { + id: UUID; + title: string; + } + |] + (recordInterface table) `shouldBe` expected + + describe "newRcordInterface" do + it "should generate optional fields for fields with default values" do + let table = CreateTable + { name = "tasks" + , columns = + [ Column { name = "id", columnType = PUUID, defaultValue = Just (CallExpression "uuid_generate_v4" []), notNull = True, isUnique = False, generator = Nothing } + , Column { name = "title", columnType = PText, defaultValue = Just (TextExpression "untitled"), notNull = True, isUnique = False, generator = Nothing } + ] + , primaryKeyConstraint = PrimaryKeyConstraint ["id"] + , constraints = [] + , unlogged = False + } + let expected = [trimming| + /** + * A Task object not yet inserted into the `tasks` table + */ + interface NewTask { + id?: UUID; + title?: string; + } + |] + (newRecordInterface table) `shouldBe` expected + + describe "newRecordType" do + it "should generate a type that maps record types to their New variant" do + let tasks = CreateTable + { name = "tasks" + , columns = [] + , primaryKeyConstraint = PrimaryKeyConstraint ["id"] + , constraints = [] + , unlogged = False + } + let users = (tasks :: CreateTable) { name = "users" } + let projects = (tasks :: CreateTable) { name = "projects" } + + let expected = [trimming| + type NewRecord = Type extends User ? NewUser : (Type extends Task ? NewTask : (Type extends Project ? NewProject : (never))); + |] + (newRecordType [ users, tasks, projects ]) `shouldBe` expected + +parseSqlStatements :: Text -> [Statement] +parseSqlStatements sql = + case Megaparsec.runParser Parser.parseDDL "input" sql of + Left parserError -> error (cs $ Megaparsec.errorBundlePretty parserError) -- For better error reporting in hspec + Right statements -> statements diff --git a/ihp-datasync-typescript/exe/GenerateDataSyncTypes.hs b/ihp-datasync-typescript/exe/GenerateDataSyncTypes.hs new file mode 100644 index 000000000..f9e110a3e --- /dev/null +++ b/ihp-datasync-typescript/exe/GenerateDataSyncTypes.hs @@ -0,0 +1,28 @@ +module Main where + +import IHP.Prelude +import IHP.SchemaCompiler +import Main.Utf8 (withUtf8) +import qualified Data.Text.IO as Text +import qualified IHP.IDE.SchemaDesigner.Parser as Parser +import qualified IHP.DataSync.TypeScript.Compiler as Compiler + +main :: IO () +main = withUtf8 do + (sqlPath, tsPath) <- decodeArgs + errorOrSchema <- Parser.parseSqlFile sqlPath + + case errorOrSchema of + Left error -> fail (cs error) + Right schema -> do + let types = Compiler.generateTypeScriptTypeDefinitions schema + + Text.writeFile tsPath types + +decodeArgs :: IO (String, String) +decodeArgs = do + args <- getArgs + + case args of + [sqlPath, tsPath] -> pure (cs sqlPath, cs tsPath) + otherwise -> fail "Invalid usage: generate-datasync-types Schema.sql Schema.ts" \ No newline at end of file diff --git a/ihp-datasync-typescript/ihp-datasync-typescript.cabal b/ihp-datasync-typescript/ihp-datasync-typescript.cabal new file mode 100644 index 000000000..b5351f02d --- /dev/null +++ b/ihp-datasync-typescript/ihp-datasync-typescript.cabal @@ -0,0 +1,72 @@ +cabal-version: 2.2 +name: ihp-datasync-typescript +version: 1.3.0 +synopsis: TypeScript code generation for IHP DataSync +description: Generates TypeScript type interfaces from the IHP Schema.sql +license: MIT +author: digitally induced GmbH +maintainer: support@digitallyinduced.com +bug-reports: https://github.com/digitallyinduced/ihp/issues +category: Database +build-type: Simple +extra-source-files: README.md + +source-repository head + type: git + location: https://github.com/digitallyinduced/ihp.git + +common shared-properties + default-language: Haskell2010 + default-extensions: + OverloadedStrings + , NoImplicitPrelude + , ImplicitParams + , Rank2Types + , NamedFieldPuns + , TypeSynonymInstances + , FlexibleInstances + , DisambiguateRecordFields + , DuplicateRecordFields + , OverloadedLabels + , FlexibleContexts + , DataKinds + , QuasiQuotes + , TypeFamilies + , PackageImports + , ScopedTypeVariables + , RecordWildCards + , TypeApplications + , DataKinds + , InstanceSigs + , DeriveGeneric + , MultiParamTypeClasses + , TypeOperators + , DeriveDataTypeable + , DefaultSignatures + , BangPatterns + , FunctionalDependencies + , PartialTypeSignatures + , BlockArguments + , LambdaCase + , StandaloneDeriving + , TemplateHaskell + , OverloadedRecordDot + +library + import: shared-properties + hs-source-dirs: . + exposed-modules: IHP.DataSync.TypeScript.Compiler + build-depends: ihp, ihp-ide, neat-interpolation + +executable generate-datasync-types + import: shared-properties + build-depends: ihp-datasync-typescript, ihp, ihp-ide, neat-interpolation, with-utf8, text + hs-source-dirs: . + main-is: exe/GenerateDataSyncTypes.hs + +test-suite spec + import: shared-properties + type: exitcode-stdio-1.0 + hs-source-dirs: . + main-is: Test/Spec.hs + build-depends: ihp-datasync-typescript, ihp, ihp-ide, megaparsec, neat-interpolation, hspec \ No newline at end of file