@alevnyacow/nzmt 0.14.1 → 0.15.1

package/README.md

@@ -6,35 +6,32 @@
 
 # About
 
-NZMT is a toolkit for building structured Next.js full-stack applications.
+**Not** a framework. Seriously, we have enough of those. NZMT is just the tools you always wanted in Next.js, plus a scaffolder that spins up server logic and client queries. Full-stack, the Next.js way!
 
-It combines dependency injection, Zod validation and a DDD-inspired architecture,
-while removing most of the boilerplate through code generation out of the box.
+Think: dependency injection + Zod validation + DDD vibes... but without drowning in boilerplate. You write the fun stuff; NZMT handles the boring stuff.
 
-Batteries included!
+Batteries included.
 
 ## Why NZMT?
 
-- You want to focus on domain logic without full DDD complexity
-- You’re tired of rewriting CRUD, data layer logic, DTOs, and validation
-- You want to follow best practices without overengineering or repetitive boilerplate
-- You want your application to be runtime-safe
-- You want to move fast without losing predictability
-- You want a backend that can evolve into a full-stack solution
-- You dig cool cartoonish fonts in logos
+- Focus on your domain logic without drowning in full-blown DDD.
+- Keep using plain Next.js, just faster and cleaner — no extra framework required.
+- Watch entities, stores, services, controllers, handlers, and client-side queries appear automatically (and yes, it’s actually fun).
 
-You focus on business logic; NZMT handles the infrastructure.
+# Quick start (Prisma + client-side queries)
 
-# Quick start with Prisma 
+Assuming you have a Next.js project with a generated Prisma client, `User` Prisma model and configured `@tanstack/react-query`:
 
-Assuming you have a Next.js project with a generated Prisma client and a `User` Prisma model:
+## Initialization
+
+1. Install required dependencies and NZMT itself:
 
-1. Install required peer dependencies and the toolkit itself.
 ```bash
 npm install inversify zod reflect-metadata @alevnyacow/nzmt
 ```
 
 2. Enable `Experimental decorators` and `Emit Decorator Metadata` options in your `tsconfig.json`.
+
 ```json
 {
   "compilerOptions": {
@@ -45,11 +42,15 @@ npm install inversify zod reflect-metadata @alevnyacow/nzmt
 ```
 
 3. Initialize NZMT (must be done once). This will set up all required infrastructure and configuration for you:
+
 ```bash
 npx nzmt init prismaClientPath:@/app/generated/prisma/client
 ```
 
-4. Now you can scaffold everything you need for `User` entity CRUD API in one CLI command:
+## Scaffolding
+
+Now you can scaffold everything you need for `User` entity CRUD API in one CLI command:
+
 ```bash
 npx nzmt crud-api user
 ```
@@ -62,12 +63,13 @@ This will generate:
 - `UserController` with ready-to-use API endpoints
 - Fully typed `UserAPI` contract (endpoints + DTOs) for client usage
 - API `route handlers` inside your `app` folder
+- `React queries`. Fully typed and ready to be used in your client-side code!
 
-All code is editable - you stay in full control.
+**All code is editable - you stay in full control!**
 
-5. **Describe entity properties and validation rules using Zod** for the `User` entity in the scaffolded file `/shared/entities/user/user.entity.ts`.
+- **Describe entity properties and validation rules using Zod** for the `User` entity in the scaffolded file `/shared/entities/user/user.entity.ts`.
 
-6. **Implement Prisma mappers** in `/server/stores/user/user.store.prisma.ts`.  
+- **Implement Prisma mappers** in `/server/stores/user/user.store.prisma.ts`.  
 All methods and contracts are already scaffolded; you only need to describe the mappers themselves. RAM store implementation works out of the box.
 
 # Design principles

package/bin/cli.js

@@ -111,6 +111,7 @@ function createDefaultConfig() {
                 entities: '/shared/entities',
                 valueObjects: '/shared/value-objects',
                 queries: '/client/shared/queries',
+                clientUtils: '/client/shared/utils'
             },
             store: {
                 prisma: {
@@ -129,6 +130,7 @@ function createDefaultConfig() {
                 entities: '/shared/entities',
                 valueObjects: '/shared/value-objects',
                 queries: '/client/shared/queries',
+                clientUtils: '/client/shared/utils'
             }
         }, null, '\t'))
     }
@@ -289,6 +291,27 @@ function initDI() {
     ].join('\n'))
 };
 
+function initClientUtils() {
+    const config = loadConfig()
+    const root = findProjectRoot()
+    const folder = path.resolve(root, `${config.coreFolder}${config.paths.clientUtils}`)
+    fs.mkdirSync(folder, { recursive: true })
+
+    fs.writeFileSync(path.resolve(folder, 'api-request.ts'), [
+        "export const apiRequest = (url: string, method: 'GET' | 'POST' | 'DELETE' | 'PATCH' | 'PUT') =>",
+        "\tasync (payload: { body?: Object; query?: Object }) => {",
+        "\t\tconst query = payload?.query ? '?' + new URLSearchParams(Object.entries(payload.query).filter(([, v]) => v != null && v !== '')) : ''",
+        "\t\tconst res = await fetch(url + query, { method, headers: { 'Content-Type': 'application/json' }, body: payload?.body && JSON.stringify(payload.body) })",
+        "\t\tif (!res.ok) throw await res.json()",
+        "\t\treturn res.json()",
+        "\t}"
+    ].join('\n'))
+
+    fs.writeFileSync(path.resolve(folder, 'index.ts'), [
+        `export * from './api-request'`
+    ].join('\n'))
+}
+
 function initPrisma() {
     const config = loadConfig()
     const prismaClientPath = config?.store?.prisma?.clientPath
@@ -377,6 +400,7 @@ function initLogger() {
 if (command.toLowerCase() === 'init' || command === 'i') {
     createDefaultConfig()
     initDI()
+    initClientUtils()
     initPrisma()
     initLogger()
 
@@ -1030,6 +1054,108 @@ function generateAPIRoutes(lowerCase, upperCase) {
     }   
 }
 
+function generateQueries(lowerCase, upperCase) {
+    const projectRoot = findProjectRoot()
+
+    const fileText = fs.readFileSync(
+        path.resolve(projectRoot, `${config.coreFolder}${config.paths.controllers}`, entityName, `${entityName}.controller.ts`),
+        'utf-8'
+    )
+
+    const regex = /^\s*(\w+)\s*=\s*this\.endpoints/mg
+    const methods = Array.from(fileText.matchAll(regex), m => m[1])
+
+    const methodInfo = methods.map(method => ({method: method.split('_').pop(), path: method.split('_').slice(0, -1).join('/')}))
+
+    const rootMethods = methodInfo.filter(x => !x.path.length).map(x => x.method)
+    const nestedMethods = methodInfo.filter(x => !!x.path.length).reduce((acc, cur) => {
+        if (!acc[cur.path]) {
+            acc[cur.path] = []
+        }
+        acc[cur.path].push(cur.method)
+        return acc
+    }, {})
+
+    const controllerQueriesPath = path.resolve(projectRoot, `${config.coreFolder}${config.paths.queries}`, `${entityName}-controller`)
+    
+    fs.mkdirSync(controllerQueriesPath, { recursive: true })
+
+    for (const rootMethod of rootMethods) {
+        if (!rootMethod) {
+            continue
+        }
+        const fileName = path.resolve(controllerQueriesPath, `${rootMethod}.ts` )
+        const alreadyExists = fs.existsSync(fileName)
+        if (alreadyExists) {
+            continue
+        }
+        fs.writeFileSync(fileName, [
+            `import { ${rootMethod === 'GET' ? 'useQuery' : 'useMutation'} } from '@tanstack/react-query'`,
+            `import type { ${upperCase}API } from '@${config.paths.controllers}/${entityName}'`,
+            `import { apiRequest } from '@${config.paths.clientUtils}'`,
+            '',
+            `type Method = ${upperCase}API['endpoints']['${rootMethod}']`,
+            ``,
+            `const endpoint = '/api/${entityName}-controller'`,
+            ``,
+            rootMethod === 'GET' 
+                ? [
+                    `export const use${upperCase}Controller_${rootMethod} = (payload: Method['payload']) => {`,
+                    `\treturn useQuery<Method['response'], Method['error']>({`,
+                    `\t\tqueryKey: [endpoint, payload],`,
+                    `\t\tqueryFn: () => apiRequest(endpoint, 'GET')(payload)`,
+                    `\t})`,
+                    `}`
+                ].join('\n') 
+                : [
+                    `export const use${upperCase}Controller_${rootMethod} = () => {`,
+                    `\treturn useMutation<Method['response'], Method['error'], Method['payload']>({`,
+                    `\t\tmutationFn: apiRequest(endpoint, '${rootMethod}')`,
+                    `\t})`,
+                    `}`
+                ].join('\n')
+        ].join('\n'))
+    }
+
+    for (const [currentPath, methods] of Object.entries(nestedMethods)) {
+        for (const method of methods) {
+            const fullMethodName = `${currentPath.replaceAll('/', '_')}_${method}`
+            const fileName = path.resolve(controllerQueriesPath, `${fullMethodName}.ts`)
+            const alreadyExists = fs.existsSync(fileName)
+            if (alreadyExists) {
+                continue
+            }
+            fs.writeFileSync(fileName, [
+                `import { ${method === 'GET' ? 'useQuery' : 'useMutation'} } from '@tanstack/react-query'`,
+                `import type { ${upperCase}API } from '@${config.paths.controllers}/${entityName}'`,
+                `import { apiRequest } from '@${config.paths.clientUtils}'`,
+                '',
+                `type Method = ${upperCase}API['endpoints']['${fullMethodName}']`,
+                ``,
+                `const endpoint = '/api/${entityName}-controller/${currentPath}'`,
+                ``,
+                method === 'GET' 
+                    ? [
+                        `export const use${upperCase}Controller_${fullMethodName} = (payload: Method['payload']) => {`,
+                        `\treturn useQuery<Method['response'], Method['error']>({`,
+                        `\t\tqueryKey: [endpoint, payload],`,
+                        `\t\tqueryFn: () => apiRequest(endpoint, 'GET')(payload)`,
+                        `\t})`,
+                        `}`
+                    ].join('\n') 
+                    : [
+                        `export const use${upperCase}Controller_${fullMethodName} = () => {`,
+                        `\treturn useMutation<Method['response'], Method['error'], Method['payload']>({`,
+                        `\t\tmutationFn: apiRequest(endpoint, '${method}')`,
+                        `\t})`,
+                        `}`
+                    ].join('\n')
+            ].join('\n'))
+
+        }
+    }   
+}
+
 
 if (command === 'api-routes') {
     var [lowerCase, upperCase] = camelizeVariants(entityName)
@@ -1037,6 +1163,13 @@ if (command === 'api-routes') {
     generateAPIRoutes(lowerCase, upperCase)
 }
 
+if (command === 'queries') {
+    var [lowerCase, upperCase] = camelizeVariants(entityName)
+
+    generateQueries(lowerCase, upperCase)
+
+}
+
 if (command.toLowerCase() === 'controller' || command === 'c') {
     var [lowerCase, upperCase] = camelizeVariants(entityName)
     generateController(upperCase, lowerCase)
@@ -1065,5 +1198,6 @@ if (command.toLowerCase() === 'crud-api') {
     generateService(lowerCase, upperCase, upperCase + 'Store')
     generateController(upperCase, lowerCase, upperCase + 'Service')
     generateAPIRoutes(lowerCase, upperCase)
+    generateQueries(lowerCase, upperCase)
     process.exit(0)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alevnyacow/nzmt",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "description": "Next Zod Modules Toolkit",
   "repository": {
     "type": "git",