@innet/server 2.0.0-beta.1 → 2.0.0-beta.10

package/README.md

@@ -581,7 +581,7 @@ This section contains elements of utils.
 
 [← back](#index)
 
-[\<swagger>](#swagger)  
+[\<ui>](#ui)  
 [\<env>](#env)  
 [\<dts>](#dts)  
 [\<blacklist>](#blacklist)  
@@ -590,40 +590,151 @@ This section contains elements of utils.
 
 ---
 
-### \<swagger>
+### \<ui>
 
 [← back](#utils)
 
-Use `<swagger>` element to add Swagger UI documentation.
-`<swagger>` element MUST be placed in `<api>` element.
+Use `<ui>` element to add API documentation UI. This element supports multiple documentation viewers including Swagger UI, RapiDoc, ReDoc, and Scalar.
+`<ui>` element MUST be placed in `<api>` element.
 
 *src/app.tsx*
 ```typescript jsx
 export default (
   <server>
     <api>
-      <swagger />
+      <ui />
     </api>
   </server>
 )
 ```
 
-Open http://localhost:80/swagger-ui
-You will see Swagger UI documentation.
+Open http://localhost:80/ui
+You will see Swagger UI documentation by default.
 
-You can change the Swagger UI URL path by `path` property of `<swagger>` element.
+#### html
+
+You can provide custom HTML template for the documentation viewer.
+Built-in presets are available: `uiPresets.swagger`, `uiPresets.rapidoc`, `uiPresets.redoc`, `uiPresets.scalar`.
+
+*src/app.tsx*
+```typescript jsx
+import { uiPresets } from '@innet/server'
+
+export default (
+  <server>
+    <api>
+      <ui html={uiPresets.rapidoc} />
+    </api>
+  </server>
+)
+```
+
+#### params
+
+You can pass additional parameters to the documentation viewer. Parameters depend on the selected UI library.
+
+For **Swagger UI** (default):
 
 *src/app.tsx*
 ```typescript jsx
 export default (
   <server>
     <api>
-      <swagger path='/swagger' />
+      <ui
+        params={{
+          docExpansion: 'full',
+          filter: true,
+          showExtensions: true,
+        }}
+      />
     </api>
   </server>
 )
 ```
 
+For **Scalar**:
+
+*src/app.tsx*
+```typescript jsx
+import { uiPresets } from '@innet/server'
+
+export default (
+  <server>
+    <api>
+      <ui
+        html={uiPresets.scalar}
+        params={{
+          theme: 'moon',
+          layout: 'classic',
+        }}
+      />
+    </api>
+  </server>
+)
+```
+
+For **RapiDoc**:
+
+*src/app.tsx*
+```typescript jsx
+import { uiPresets } from '@innet/server'
+
+export default (
+  <server>
+    <api>
+      <ui
+        html={uiPresets.rapidoc}
+        params={{
+          theme: 'dark',
+          layout: 'row',
+          showHeader: 'false',
+        }}
+      />
+    </api>
+  </server>
+)
+```
+
+For **ReDoc**:
+
+*src/app.tsx*
+```typescript jsx
+import { uiPresets } from '@innet/server'
+
+export default (
+  <server>
+    <api>
+      <ui
+        html={uiPresets.redoc}
+        params={{
+          disableSearch: 'true',
+          hideDownloadButton: 'true',
+          nativeScrollbars: 'true',
+          theme: '{"sidebar": {"backgroundColor": "#d1e5ef"}}',
+        }}
+      />
+    </api>
+  </server>
+)
+```
+
+#### path
+
+You can change the documentation UI URL path by `path` property of `<ui>` element.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <ui path='/docs' />
+    </api>
+  </server>
+)
+```
+
+*default: `INNET_UI_PATH` || `'/ui'`*
+
 ### \<env>
 
 [← back](#utils)
@@ -1396,6 +1507,28 @@ export default (
 )
 ```
 
+#### operationId
+
+`operationId` is an optional unique string used to identify an operation.
+If provided, these IDs must be unique among all operations described in your API.
+
+Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint
+        method='get'
+        path='/users'
+        operationId='getUsers'
+      />
+    </api>
+  </server>
+)
+```
+
 ### \<tag>
 
 [← back](#endpoints)
@@ -1423,6 +1556,34 @@ export default (
 )
 ```
 
+#### group
+
+You can organize tags into groups using the `group` property.
+This adds tag groups support to the OpenAPI specification,
+which is displayed in documentation viewers.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <tag group='Authentication' name='auth'>
+        <endpoint method='post' path='/login' />
+        <endpoint method='post' path='/logout' />
+      </tag>
+      <tag group='Users' name='users'>
+        <endpoint method='get' path='/users' />
+        <endpoint method='post' path='/users' />
+      </tag>
+    </api>
+  </server>
+)
+```
+
+This will create tag groups in your OpenAPI documentation:
+- **Authentication** group containing the `auth` tag
+- **Users** group containing the `users` tag
+
 ### \<param>
 
 [← back](#endpoints)
@@ -2154,6 +2315,26 @@ you get an error:
 }
 ```
 
+#### format
+
+An optional format modifier serves as a hint at the contents and format of the string.
+Available formats include: `email`, `date-time`, `date`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `byte`, `binary`, `password` or custom string.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/users'>
+        <param in='query' name='email'>
+          <string format='email' />
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
 ### \<number>
 
 [← back](#primitive-data)
@@ -2303,6 +2484,66 @@ export default (
 
 *In this example `/products?rating=5` is valid and `/products?rating=6` is not*
 
+#### exclusiveMinimum, exclusiveMaximum
+
+These props restrict the value to be strictly greater than or less than the specified number.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/products'>
+        <param in='query' name='rating'>
+          <number 
+            exclusiveMinimum={0}
+            exclusiveMaximum={5}
+          />
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
+#### multipleOf
+
+This prop restricts the value to be a multiple of the specified number.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/products'>
+        <param in='query' name='quantity'>
+          <number multipleOf={10} />
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
+#### format
+
+An optional format modifier serves as a hint at the contents and format of the number.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/products'>
+        <param in='query' name='price'>
+          <number format='float' />
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
 ### \<integer>
 
 [← back](#primitive-data)
@@ -2476,6 +2717,47 @@ export default (
 
 *In this example `/products?rating=5` is valid and `/products?rating=6` is not*
 
+#### exclusiveMinimum, exclusiveMaximum
+
+These props restrict the value to be strictly greater than or less than the specified number.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/products'>
+        <param in='query' name='count'>
+          <integer 
+            exclusiveMinimum={0}
+            exclusiveMaximum={100}
+          />
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
+#### multipleOf
+
+This prop restricts the value to be a multiple of the specified number.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/products'>
+        <param in='query' name='quantity'>
+          <integer multipleOf={5} />
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
 ### \<date>
 
 [← back](#primitive-data)
@@ -3113,6 +3395,48 @@ export default (
 )
 ```
 
+#### minItems, maxItems
+
+Those two props validate the array by minimum and maximum number of items.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/products'>
+        <param in='query' name='tags'>
+          <array minItems={1} maxItems={10}>
+            <string />
+          </array>
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
+#### uniqueItems
+
+This prop validates that all items in the array are unique.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/products'>
+        <param in='query' name='ids'>
+          <array uniqueItems>
+            <number />
+          </array>
+        </param>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
 ### \<object>
 
 [← back](#list-of-data)
@@ -3276,6 +3600,58 @@ export default (
 )
 ```
 
+#### readOnly
+
+You can mark a field as read-only, meaning it can only be returned in responses, not sent in requests.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='get' path='/users'>
+        <response>
+          <object>
+            <field key='id' readOnly>
+              <uuid />
+            </field>
+            <field key='name'>
+              <string />
+            </field>
+          </object>
+        </response>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
+#### writeOnly
+
+You can mark a field as write-only, meaning it can only be sent in requests, not returned in responses.
+
+*src/app.tsx*
+```typescript jsx
+export default (
+  <server>
+    <api>
+      <endpoint method='post' path='/users'>
+        <body>
+          <object>
+            <field key='password' writeOnly>
+              <string />
+            </field>
+            <field key='name'>
+              <string />
+            </field>
+          </object>
+        </body>
+      </endpoint>
+    </api>
+  </server>
+)
+```
+
 ## Run-Time
 
 Next elements relate to run-time action.

package/handler/handler.d.ts

@@ -1,6 +1,6 @@
-import { context, type ContextProps, type JSXElement, slot, type SlotProps, slots, type SlotsProps } from '@innet/jsx';
+import { type JSXElement } from '@innet/jsx';
 import { arraySync, async } from '@innet/utils';
-import { type AnyProps, type ApiProps, type ArrayProps, type BinaryProps, blacklist, type BlacklistProps, type BodyProps, type BooleanProps, cms, type CmsProps, type ContactProps, type CookieProps, type DateProps, type DtsProps, type EndpointProps, type EnvProps, type ErrorProps, type FieldProps, file, type FileProps, type HeaderProps, type HostProps, type IntegerProps, type LicenseProps, type NullProps, type NumberProps, type ObjectProps, type ParamProps, preset, type PresetProps, protection, type ProtectionProps, type ProxyProps, type RedirectProps, type ResponseProps, type ReturnProps, type ServerProps, type StringProps, type SuccessProps, type SwaggerProps, type TagProps, type TupleProps, type UuidProps, type VariableProps, whitelist, type WhitelistProps } from '../plugins';
+import { type AnyProps, type ApiProps, type ArrayProps, type BinaryProps, blacklist, type BlacklistProps, type BodyProps, type BooleanProps, cms, type CmsProps, type ContactProps, type CookieProps, type DateProps, type DtsProps, type EndpointProps, type EnvProps, type ErrorProps, type FieldProps, file, type FileProps, type HeaderProps, type HostProps, type IntegerProps, type LicenseProps, type NullProps, type NumberProps, type ObjectProps, type ParamProps, preset, type PresetProps, protection, type ProtectionProps, type ProxyProps, type RedirectProps, type ResponseProps, type ReturnProps, type ServerProps, type StringProps, type SuccessProps, type SwaggerProps, type TagProps, type TupleProps, type UiProps, type UuidProps, type VariableProps, whitelist, type WhitelistProps } from '../plugins';
 export declare const arrayPlugins: (typeof arraySync)[];
 export declare const JSXPlugins: {
     any: import("innet").HandlerPlugin;
@@ -12,7 +12,6 @@ export declare const JSXPlugins: {
     boolean: import("innet").HandlerPlugin;
     cms: typeof cms;
     contact: import("innet").HandlerPlugin;
-    context: typeof context;
     cookie: import("innet").HandlerPlugin;
     date: import("innet").HandlerPlugin;
     dts: import("innet").HandlerPlugin;
@@ -36,13 +35,12 @@ export declare const JSXPlugins: {
     response: import("innet").HandlerPlugin;
     return: import("innet").HandlerPlugin;
     server: import("innet").HandlerPlugin;
-    slot: typeof slot;
-    slots: typeof slots;
     string: import("innet").HandlerPlugin;
     success: import("innet").HandlerPlugin;
     swagger: import("innet").HandlerPlugin;
     tag: import("innet").HandlerPlugin;
     tuple: import("innet").HandlerPlugin;
+    ui: import("innet").HandlerPlugin;
     uuid: import("innet").HandlerPlugin;
     variable: import("innet").HandlerPlugin;
     whitelist: typeof whitelist;
@@ -53,7 +51,7 @@ export declare const promisePlugins: (typeof async)[];
 export declare const handler: import("innet").Handler;
 declare global {
     namespace JSX {
-        type Element = ArrayElement | FunctionElement | JSXElement | boolean | null | number | (string & {}) | undefined;
+        type Element = ({} & string) | ArrayElement | FunctionElement | JSXElement | boolean | null | number | undefined;
         interface ArrayElement extends Array<Element> {
         }
         type FunctionElement = () => Element;
@@ -70,7 +68,6 @@ declare global {
             boolean: BooleanProps;
             cms: CmsProps;
             contact: ContactProps;
-            context: ContextProps;
             cookie: CookieProps;
             date: DateProps;
             dts: DtsProps;
@@ -94,13 +91,13 @@ declare global {
             response: ResponseProps;
             return: ReturnProps;
             server: ServerProps;
-            slot: SlotProps;
-            slots: SlotsProps;
             string: StringProps;
             success: SuccessProps;
+            /** @deprecated Use <ui> */
             swagger: SwaggerProps;
             tag: TagProps;
             tuple: TupleProps;
+            ui: UiProps;
             uuid: UuidProps;
             variable: VariableProps;
             whitelist: WhitelistProps;

package/handler/handler.es6.js

@@ -1,5 +1,5 @@
 import { createHandler } from 'innet';
-import { context, slot, slots, jsxPlugins, jsxComponent } from '@innet/jsx';
+import { jsxPlugins, jsxComponent } from '@innet/jsx';
 import { arraySync, async, promise, array as array$1, nullish, object as object$1, fn } from '@innet/utils';
 import '../plugins/index.es6.js';
 import { any } from '../plugins/schema/any/any.es6.js';
@@ -39,6 +39,7 @@ import { success } from '../plugins/request/success/success.es6.js';
 import { swagger } from '../plugins/utils/swagger/swagger.es6.js';
 import { tag } from '../plugins/main/tag/tag.es6.js';
 import { tuple } from '../plugins/schema/tuple/tuple.es6.js';
+import { ui } from '../plugins/utils/ui/ui.es6.js';
 import { uuid } from '../plugins/schema/uuid/uuid.es6.js';
 import { variable } from '../plugins/main/variable/variable.es6.js';
 import { whitelist } from '../plugins/utils/whitelist/whitelist.es6.js';
@@ -57,7 +58,6 @@ const JSXPlugins = {
     boolean,
     cms,
     contact,
-    context,
     cookie,
     date,
     dts,
@@ -81,13 +81,12 @@ const JSXPlugins = {
     response,
     return: returnPlugin,
     server,
-    slot,
-    slots,
     string,
     success,
     swagger,
     tag,
     tuple,
+    ui,
     uuid,
     variable,
     whitelist,

package/handler/handler.js

@@ -43,6 +43,7 @@ var success = require('../plugins/request/success/success.js');
 var swagger = require('../plugins/utils/swagger/swagger.js');
 var tag = require('../plugins/main/tag/tag.js');
 var tuple = require('../plugins/schema/tuple/tuple.js');
+var ui = require('../plugins/utils/ui/ui.js');
 var uuid = require('../plugins/schema/uuid/uuid.js');
 var variable = require('../plugins/main/variable/variable.js');
 var whitelist = require('../plugins/utils/whitelist/whitelist.js');
@@ -61,7 +62,6 @@ const JSXPlugins = {
     boolean: boolean.boolean,
     cms: cms.cms,
     contact: contact.contact,
-    context: jsx.context,
     cookie: cookie.cookie,
     date: date.date,
     dts: dts.dts,
@@ -85,13 +85,12 @@ const JSXPlugins = {
     response: response.response,
     return: _return.returnPlugin,
     server: server.server,
-    slot: jsx.slot,
-    slots: jsx.slots,
     string: string.string,
     success: success.success,
     swagger: swagger.swagger,
     tag: tag.tag,
     tuple: tuple.tuple,
+    ui: ui.ui,
     uuid: uuid.uuid,
     variable: variable.variable,
     whitelist: whitelist.whitelist,

package/hooks/index.d.ts

@@ -1,32 +1,33 @@
-export * from './useServer';
+export * from './useAction';
 export * from './useApi';
-export * from './useHost';
-export * from './useTag';
-export * from './useComponentName';
-export * from './useOneElementError';
-export * from './useSchemaContext';
-export * from './useSchemaType';
-export * from './useNewSchema';
-export * from './useRequest';
-export * from './useResponse';
-export * from './useParams';
+export * from './useBlock';
 export * from './useBody';
-export * from './useSearch';
-export * from './useParam';
+export * from './useBodyFile';
+export * from './useClientIp';
+export * from './useComponentName';
+export * from './useCookies';
+export * from './useEffect';
 export * from './useEndpoint';
-export * from './useBlock';
 export * from './useHeaders';
-export * from './useCookies';
-export * from './useAction';
-export * from './useThrow';
-export * from './useRule';
+export * from './useHost';
+export * from './useIsServerHttps';
+export * from './useNewSchema';
 export * from './useObjectRule';
-export * from './useBodyFile';
+export * from './useObjectSchemaContext';
+export * from './useOneElementError';
+export * from './useParam';
+export * from './useParams';
 export * from './usePath';
+export * from './useRequest';
+export * from './useRequestHandler';
+export * from './useResponse';
+export * from './useRule';
+export * from './useSchemaContext';
+export * from './useSchemaType';
+export * from './useSearch';
+export * from './useServer';
 export * from './useServerPlugin';
-export * from './useClientIp';
 export * from './useServerPlugins';
-export * from './useObjectSchemaContext';
 export * from './useServerPort';
-export * from './useIsServerHttps';
-export * from './useRequestHandler';
+export * from './useTag';
+export * from './useThrow';