vovk-cli 0.0.1-draft.17 → 0.0.1-draft.170

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-present Andrii Gubanov
+Copyright (c) 2023-present Andrey Gubanov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1 +1,29 @@
-Description is coming soon.
+<p align="center"> 
+  <picture>
+    <source width="300" media="(prefers-color-scheme: dark)" srcset="https://vovk.dev/vovk-logo-white.svg">
+    <source width="300" media="(prefers-color-scheme: light)" srcset="https://vovk.dev/vovk-logo.svg">
+    <img width="300" alt="vovk" src="https://vovk.dev/vovk-logo.svg">
+  </picture><br>
+  <strong>RESTful + RPC = ♥️</strong>
+</p>
+
+<p align="center">
+  Back-end meta-framework for <a href="https://nextjs.org/docs/app">Next.js</a>
+</p>
+
+---
+
+## vovk-cli [![npm version](https://badge.fury.io/js/vovk-cli.svg)](https://www.npmjs.com/package/vovk-cli)
+
+The Vovk.ts CLI that generates schema and client but also provides some useful utilities for the development process.
+
+```sh
+npm install -D vovk-cli
+```
+
+- [vovk dev](https://vovk.dev/cli/vovk-dev) - starts the development script that watches the changes in controllers and regenerates the schema and client.
+- [vovk generate](https://vovk.dev/cli/vovk-generate) - generates the client based on the schema.
+- [vovk init](https://vovk.dev/cli/vovk-init) - initializes the Vovk.ts project.
+- [vovk new](https://vovk.dev/cli/vovk-new) - generates a new controller, service or a custom module.
+
+For more information, please visit the [CLI documentation](https://vovk.dev/cli) or use `npx vovk-cli --help` to get the list of available commands and options.

package/client-templates/cjs/index.cjs.ejs

@@ -0,0 +1,14 @@
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+const { fetcher } = require('<%= t.imports.fetcher %>');
+const { createRPC } = require('<%= t.imports.createRPC %>');
+const { schema } = require('./schema.cjs');
+const { validateOnClient = null } = <%- t.imports.validateOnClient ? `require('${t.imports.validateOnClient}')` : '{}'%>;
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment) => { 
+  Object.keys(segment.controllers).forEach((rpcModuleName) => { %>
+exports.<%= rpcModuleName %> = createRPC(
+  schema, '<%= segment.segmentName %>', '<%= rpcModuleName %>',
+  { fetcher, validateOnClient, defaultOptions: { apiRoot: '<%= segment.segmentApiRoot ?? t.apiRoot %>' } }
+);
+  <% })
+}) %>
+exports.schema = schema;

package/client-templates/cjs/index.d.cts.ejs

@@ -0,0 +1,15 @@
+
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+import type { VovkClientFetcher } from 'vovk';
+import type { fetcher } from '<%= t.imports.module.fetcher %>';
+import type { createRPC } from '<%= t.imports.module.createRPC %>';
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { %>
+import type { Controllers as Controllers<%= i %> } from "<%= t.segmentMeta[segment.segmentName].segmentImportPath %>";
+<% }) %>
+type Options = typeof fetcher extends VovkClientFetcher<infer U> ? U : never;
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { 
+  Object.keys(segment.controllers).forEach((rpcModuleName) => { %>
+export const <%= rpcModuleName %>: ReturnType<typeof createRPC<Controllers<%= i %>["<%= rpcModuleName %>"], Options>>;
+  <% }) 
+}) %>
+export { schema } from './schema.cjs';

package/client-templates/mjs/index.d.mts.ejs

@@ -0,0 +1,15 @@
+
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+import type { VovkClientFetcher } from 'vovk';
+import type { fetcher } from '<%= t.imports.module.fetcher %>';
+import type { createRPC } from '<%= t.imports.module.createRPC %>';
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { %>
+import type { Controllers as Controllers<%= i %> } from "<%= t.segmentMeta[segment.segmentName].segmentImportPath %>";
+<% }) %>
+type Options = typeof fetcher extends VovkClientFetcher<infer U> ? U : never;
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { 
+  Object.keys(segment.controllers).forEach((rpcModuleName) => { %>
+export const <%= rpcModuleName %>: ReturnType<typeof createRPC<Controllers<%= i %>["<%= rpcModuleName %>"], Options>>;
+  <% }) 
+}) %>
+export { schema } from './schema.cjs';

package/client-templates/mjs/index.mjs.ejs

@@ -0,0 +1,20 @@
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+import { fetcher } from '<%= t.imports.module.fetcher %>';
+import { createRPC } from '<%= t.imports.module.createRPC %>';
+import { schema } from './schema.cjs';
+<% if (t.imports.module.validateOnClient) { %>
+import { validateOnClient } from '<%= t.imports.module.validateOnClient %>';
+<% } else { %>
+const validateOnClient = undefined;
+<% } %>
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => {
+  Object.keys(segment.controllers).forEach((rpcModuleName) => { %>
+export const <%= rpcModuleName %> = createRPC(
+  schema, '<%= segment.segmentName %>', '<%= rpcModuleName %>',
+  { fetcher, validateOnClient, defaultOptions: { apiRoot: '<%= segment.segmentApiRoot ?? t.apiRoot %>' } }
+);
+<% 
+  }); 
+});
+%>
+export { schema };

package/client-templates/packageJson/package.json.ejs

@@ -0,0 +1 @@
+<%- JSON.stringify(t.package, null, 2) %>

package/client-templates/readme/README.md.ejs

@@ -0,0 +1,41 @@
+---
+imports: ['vovk-openapi']
+---
+<% const vars = {
+    createCodeExamples: t.imports['vovk-openapi'].createCodeExamples,
+}; %>
+
+# <%= t.package.name %> v<%= t.package.version %>
+
+<%- t.package.description ? `> ${t.package.description}` : '' %>
+
+<%- t.package.license ? `License: **${t.package.license}**` : '' %>
+
+```bash
+# Install the package
+npm install <%= t.package.name.replace(/-/g, '_') %>
+```
+
+<% Object.entries(t.schema.segments).forEach(([segmentName, segment]) => {
+    Object.values(segment.controllers).forEach((controllerSchema) => { %>
+
+## <%= controllerSchema.rpcModuleName %>
+        <% Object.entries(controllerSchema.handlers).forEach(([handlerName, handlerSchema]) => { %>
+### <%= controllerSchema.rpcModuleName %>.<%= handlerName %>
+<%- handlerSchema.openapi?.summary ? `> ${handlerSchema.openapi.summary}` : '' %>
+
+<%- handlerSchema.openapi?.description ? `${handlerSchema.openapi.description}` : '' %>
+
+Endpoint: <%= t.apiRoot %>/<%= segmentName %>/<%= controllerSchema.prefix %>/<%= handlerSchema.path %>
+
+```ts
+<%- vars.createCodeExamples({
+    handlerSchema,
+    handlerName,
+    controllerSchema,
+    package: t.package,
+}).ts %>
+```
+        <% }) %>
+    <% }) %>
+<% }) %>

package/client-templates/schemaCjs/schema.cjs.ejs

@@ -0,0 +1,12 @@
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+const config = require('./<%= t.schemaOutDir %>/config.json');
+const segments = {<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment) => { %>
+    '<%= segment.segmentName %>': require('./<%= t.schemaOutDir %>/<%= t.SEGMENTS_SCHEMA_DIR_NAME %>/<%= segment.segmentName || t.ROOT_SEGMENT_SCHEMA_NAME %>.json'),<% }) %>
+};
+const schema = {
+  $schema: '<%- t.VovkSchemaIdEnum.FULL %>',
+  config,
+  segments,
+};
+
+module.exports.schema = schema;

package/client-templates/schemaCjs/schema.d.cts.ejs

@@ -0,0 +1,10 @@
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+import type { VovkStrictConfig, VovkSegmentSchema, VovkSchemaIdEnum } from 'vovk';
+
+export const schema: {
+    $schema: '<%- t.VovkSchemaIdEnum.FULL %>';
+    config: Partial<VovkStrictConfig>;
+    segments: {<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment) => { %>
+      '<%= segment.segmentName %>': VovkSegmentSchema;<% }) %>
+    };
+};

package/client-templates/schemaJson/schema.json.ejs

@@ -0,0 +1 @@
+<%- JSON.stringify(t.schema, null, 2) %>

package/client-templates/schemaTs/schema.ts.ejs

@@ -0,0 +1,14 @@
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+import config from './<%= t.schemaOutDir %>/config.json' with { type: "json" };
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { %>
+import segment<%= i %> from './<%= t.schemaOutDir %>/<%= t.SEGMENTS_SCHEMA_DIR_NAME %>/<%= segment.segmentName || t.ROOT_SEGMENT_SCHEMA_NAME %>.json' with { type: "json" };
+<% }) %>
+const segments = {<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { %>
+  '<%= segment.segmentName %>': segment<%= i %>,<% }) %>
+};
+
+export const schema = {
+  $schema: '<%- t.VovkSchemaIdEnum.FULL %>',
+  config,
+  segments,
+};

package/client-templates/ts/index.ts.ejs

@@ -0,0 +1,23 @@
+<%- `// auto-generated ${new Date().toISOString()}\n/* eslint-disable */` %>
+import type { VovkClientFetcher } from 'vovk';
+import { fetcher } from '<%= t.imports.fetcher %>';
+import { createRPC } from '<%= t.imports.createRPC %>';
+import { schema } from './schema.ts';
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { %>
+import type { Controllers as Controllers<%= i %> } from "<%= t.segmentMeta[segment.segmentName].segmentImportPath %>";
+<% }) %>
+<% if (t.imports.validateOnClient) { %>
+import { validateOnClient } from '<%= t.imports.validateOnClient %>';
+<% } else { %>
+const validateOnClient = undefined;
+<% } %>
+type Options = typeof fetcher extends VovkClientFetcher<infer U> ? U : never;
+<% Object.values(t.schema.segments).filter((segment) => segment.emitSchema).forEach((segment, i) => { %>
+  <% Object.keys(segment.controllers).forEach((rpcModuleName) => { %>
+export const <%= rpcModuleName %> = createRPC<Controllers<%= i %>["<%= rpcModuleName %>"], Options>(
+  schema, '<%= segment.segmentName %>', '<%= rpcModuleName %>',
+  { fetcher, validateOnClient, defaultOptions: { apiRoot: '<%= segment.segmentApiRoot ?? t.apiRoot %>' } }
+);
+  <% }) %>
+<% }) %>
+export { schema };

package/dist/bundle/index.d.mts

@@ -0,0 +1,8 @@
+import type { VovkSchema } from 'vovk';
+import type { ProjectInfo } from '../getProjectInfo/index.mjs';
+import type { BundleOptions } from '../types.mjs';
+export default function bundle({ projectInfo, fullSchema, cliBundleOptions, }: {
+    projectInfo: ProjectInfo;
+    fullSchema: VovkSchema;
+    cliBundleOptions: BundleOptions;
+}): Promise<void>;

package/dist/bundle/index.mjs

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { build } from 'tsdown';
+import groupBy from 'lodash/groupBy.js';
+import generate from '../generate/index.mjs';
+import { BuiltInTemplateName } from '../getProjectInfo/getConfig/getTemplateDefs.mjs';
+import chalkHighlightThing from '../utils/chalkHighlightThing.mjs';
+import locateSegments from '../locateSegments.mjs';
+export default async function bundle({ projectInfo, fullSchema, cliBundleOptions, }) {
+    const { config, log, cwd, apiDir } = projectInfo;
+    const locatedSegments = await locateSegments({ dir: path.join(cwd, apiDir), config, log });
+    const { bundle: bundleConfig } = config;
+    const tsFullClientOutAbsoluteDirInput = path.join(cwd, bundleConfig.tsClientOutDir);
+    const tsClientOutDir = cliBundleOptions?.tsClientOutDir ?? bundleConfig.tsClientOutDir;
+    const dontDeleteTsClientOutDirAfter = cliBundleOptions?.dontDeleteTsClientOutDirAfter ?? bundleConfig?.dontDeleteTsClientOutDirAfter ?? false;
+    const sourcemap = cliBundleOptions?.sourcemap ?? bundleConfig?.sourcemap;
+    if (!tsClientOutDir) {
+        throw new Error('No output directory specified for composed client');
+    }
+    const outDir = cliBundleOptions?.outDir ?? bundleConfig.outDir;
+    if (!outDir) {
+        throw new Error('No output directory specified for bundling');
+    }
+    await generate({
+        isEnsuringClient: false,
+        projectInfo,
+        forceNothingWrittenLog: true,
+        fullSchema,
+        locatedSegments,
+        cliGenerateOptions: {
+            composedFrom: [BuiltInTemplateName.ts],
+            composedOut: tsClientOutDir,
+            composedOnly: true,
+            composedIncludeSegments: cliBundleOptions.includeSegments ?? bundleConfig.includeSegments,
+            composedExcludeSegments: cliBundleOptions.excludeSegments ?? bundleConfig.excludeSegments,
+        },
+    });
+    await build({
+        entry: path.join(tsFullClientOutAbsoluteDirInput, './index.ts'),
+        dts: true,
+        format: ['cjs', 'esm'],
+        fixedExtension: true,
+        outDir,
+        sourcemap: bundleConfig.sourcemap,
+    });
+    const outDirAbsolute = path.resolve(cwd, outDir);
+    log.info(`Bundled index.ts to ${chalkHighlightThing(outDirAbsolute)}`);
+    await build({
+        entry: path.join(tsFullClientOutAbsoluteDirInput, './schema.ts'),
+        dts: true,
+        format: ['cjs'],
+        fixedExtension: true,
+        outDir,
+        clean: false,
+        sourcemap,
+    });
+    log.info(`Bundled schema.ts to ${chalkHighlightThing(outDirAbsolute)}`);
+    const requiresGroup = groupBy(Object.entries(bundleConfig.requires), ([, relativePath]) => relativePath);
+    for (const [relativePath, group] of Object.entries(requiresGroup)) {
+        await generate({
+            isEnsuringClient: false,
+            projectInfo,
+            forceNothingWrittenLog: true,
+            fullSchema,
+            locatedSegments,
+            cliGenerateOptions: {
+                composedFrom: group.map(([templateName]) => templateName),
+                composedOut: path.resolve(outDir, relativePath),
+            },
+        });
+    }
+    if (!dontDeleteTsClientOutDirAfter) {
+        await fs.rm(tsFullClientOutAbsoluteDirInput, { recursive: true, force: true });
+        log.debug(`Deleted temporary TypeScript client output directory: ${chalkHighlightThing(tsFullClientOutAbsoluteDirInput)}`);
+    }
+    else {
+        log.debug(`Temporary TypeScript client output directory not deleted: ${chalkHighlightThing(tsFullClientOutAbsoluteDirInput)}`);
+    }
+    log.info(`Bundled TypeScript client to ${outDirAbsolute}`);
+}

package/dist/dev/diffSegmentSchema.d.mts

@@ -0,0 +1,36 @@
+import type { VovkControllerSchema, VovkSegmentSchema } from 'vovk';
+interface HandlersDiff {
+    nameOfClass: string;
+    added: string[];
+    removed: string[];
+    changed: string[];
+}
+interface ControllersDiff {
+    added: string[];
+    removed: string[];
+    handlers: HandlersDiff[];
+}
+export interface DiffResult {
+    controllers: ControllersDiff;
+}
+export declare function diffHandlers<T extends VovkControllerSchema['handlers']>(oldHandlers: T, newHandlers: T, nameOfClass: string): HandlersDiff;
+export declare function diffControllers<T extends VovkSegmentSchema['controllers']>(oldItems: T, newItems: T): ControllersDiff;
+/**
+example output:
+{
+  controllers: {
+    added: ["ControllerC"],
+    removed: ["ControllerB"],
+    handlers: [
+      {
+        nameOfClass: "ControllerA",
+        added: ["handlerF"],
+        removed: [],
+        changed: ["handlerD"]
+      }
+    ]
+  }
+}
+*/
+export default function diffSegmentSchema(oldJson: VovkSegmentSchema, newJson: VovkSegmentSchema): DiffResult;
+export {};

package/dist/dev/{diffSchema.mjs → diffSegmentSchema.mjs}

@@ -18,7 +18,7 @@ export function diffHandlers(oldHandlers, newHandlers, nameOfClass) {
     }
     return { nameOfClass, added, removed, changed };
 }
-export function diffWorkersOrControllers(oldItems, newItems) {
+export function diffControllers(oldItems, newItems) {
     const added = [];
     const removed = [];
     const handlersDiff = [];
@@ -27,7 +27,7 @@ export function diffWorkersOrControllers(oldItems, newItems) {
             added.push(item);
         }
         else {
-            const handlers = diffHandlers(oldItems[item]._handlers, newItem._handlers, item);
+            const handlers = diffHandlers(oldItems[item].handlers, newItem.handlers, item);
             if (handlers.added.length || handlers.removed.length || handlers.changed.length) {
                 handlersDiff.push(handlers);
             }
@@ -43,11 +43,6 @@ export function diffWorkersOrControllers(oldItems, newItems) {
 /**
 example output:
 {
-  workers: {
-    added: ["WorkerC"],
-    removed: ["WorkerA"],
-    handlers: []
-  },
   controllers: {
     added: ["ControllerC"],
     removed: ["ControllerB"],
@@ -62,11 +57,8 @@ example output:
   }
 }
 */
-export default function diffSchema(oldJson, newJson) {
-    const workersDiff = diffWorkersOrControllers(oldJson.workers ?? {}, newJson.workers ?? {});
-    const controllersDiff = diffWorkersOrControllers(oldJson.controllers ?? {}, newJson.controllers ?? {});
+export default function diffSegmentSchema(oldJson, newJson) {
     return {
-        workers: workersDiff,
-        controllers: controllersDiff,
+        controllers: diffControllers(oldJson.controllers ?? {}, newJson.controllers ?? {}),
     };
 }

package/dist/dev/ensureSchemaFiles.d.mts

@@ -1,3 +1,6 @@
 import { ProjectInfo } from '../getProjectInfo/index.mjs';
+/**
+ * Ensure that the schema files are created to avoid any import errors.
+ */
 export default function ensureSchemaFiles(projectInfo: ProjectInfo | null, schemaOutAbsolutePath: string, segmentNames: string[]): Promise<void>;
 export declare const debouncedEnsureSchemaFiles: import("lodash").DebouncedFunc<typeof ensureSchemaFiles>;

package/dist/dev/ensureSchemaFiles.mjs

@@ -1,44 +1,28 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import debounce from 'lodash/debounce.js';
-import writeOneSchemaFile, { ROOT_SEGMENT_SCHEMA_NAME } from './writeOneSchemaFile.mjs';
+import { VovkSchemaIdEnum } from 'vovk';
+import writeOneSchemaFile, { SEGMENTS_SCHEMA_DIR_NAME, ROOT_SEGMENT_SCHEMA_NAME, } from './writeOneSegmentSchemaFile.mjs';
 import formatLoggedSegmentName from '../utils/formatLoggedSegmentName.mjs';
+import writeConfigJson from './writeConfigJson.mjs';
+/**
+ * Ensure that the schema files are created to avoid any import errors.
+ */
 export default async function ensureSchemaFiles(projectInfo, schemaOutAbsolutePath, segmentNames) {
     const now = Date.now();
     let hasChanged = false;
-    // Create index.js file
-    const indexContent = `// auto-generated
-${segmentNames
-        .map((segmentName) => {
-        return `module.exports['${segmentName}'] = require('./${segmentName || ROOT_SEGMENT_SCHEMA_NAME}.json');`;
-    })
-        .join('\n')}`;
-    const dTsContent = `// auto-generated
-import type { VovkSchema } from 'vovk';
-declare const segmentSchema: {
-${segmentNames.map((segmentName) => `  '${segmentName}': VovkSchema;`).join('\n')}
-};
-export default segmentSchema;`;
-    const jsAbsolutePath = path.join(schemaOutAbsolutePath, 'index.js');
-    const dTsAbsolutePath = path.join(schemaOutAbsolutePath, 'index.d.ts');
-    const existingJs = await fs.readFile(jsAbsolutePath, 'utf-8').catch(() => null);
-    const existingDTs = await fs.readFile(dTsAbsolutePath, 'utf-8').catch(() => null);
-    await fs.mkdir(schemaOutAbsolutePath, { recursive: true });
-    if (existingJs !== indexContent) {
-        await fs.writeFile(jsAbsolutePath, indexContent);
-    }
-    if (existingDTs !== dTsContent) {
-        await fs.writeFile(dTsAbsolutePath, dTsContent);
-    }
+    const schemaJsonOutAbsolutePath = path.join(schemaOutAbsolutePath, SEGMENTS_SCHEMA_DIR_NAME);
+    await fs.mkdir(schemaJsonOutAbsolutePath, { recursive: true });
+    await writeConfigJson(schemaOutAbsolutePath, projectInfo);
     // Create JSON files (if not exist) with name [segmentName].json (where segmentName can include /, which means the folder structure can be nested)
     await Promise.all(segmentNames.map(async (segmentName) => {
         const { isCreated } = await writeOneSchemaFile({
             schemaOutAbsolutePath,
-            schema: {
+            segmentSchema: {
+                $schema: VovkSchemaIdEnum.SEGMENT,
                 emitSchema: false,
                 segmentName,
                 controllers: {},
-                workers: {},
             },
             skipIfExists: true,
         });
@@ -64,7 +48,7 @@ export default segmentSchema;`;
                 }
             }
             else if (entry.isFile() && entry.name.endsWith('.json')) {
-                const relativePath = path.relative(schemaOutAbsolutePath, absolutePath);
+                const relativePath = path.relative(schemaJsonOutAbsolutePath, absolutePath);
                 const segmentName = relativePath.replace(/\\/g, '/').slice(0, -5); // Remove '.json' extension
                 if (!segmentNames.includes(segmentName) &&
                     !segmentNames.includes(segmentName.replace(ROOT_SEGMENT_SCHEMA_NAME, ''))) {
@@ -76,8 +60,8 @@ export default segmentSchema;`;
         }));
     }
     // Start the recursive deletion from the root directory
-    await deleteUnnecessaryJsonFiles(schemaOutAbsolutePath);
+    await deleteUnnecessaryJsonFiles(schemaJsonOutAbsolutePath);
     if (hasChanged)
-        projectInfo?.log.info(`Schema files updated in ${Date.now() - now}ms`);
+        projectInfo?.log.info(`Created empty schema files in ${Date.now() - now}ms`);
 }
 export const debouncedEnsureSchemaFiles = debounce(ensureSchemaFiles, 1000);

package/dist/dev/index.d.mts

@@ -1,6 +1,6 @@
 export declare class VovkDev {
     #private;
-    start({ clientOutDir }?: {
-        clientOutDir?: string;
+    start({ exit }: {
+        exit: boolean;
     }): Promise<void>;
 }