ts-procedures 3.0.2 → 3.1.0

package/src/implementations/http/express-rpc/index.ts

@@ -1,9 +1,15 @@
 import express from 'express'
 import { kebabCase } from 'es-toolkit/string'
 import { Procedures, TProcedureRegistration } from '../../../index.js'
-import { RPCConfig, RPCHttpRouteDoc } from '../../types.js'
+import {
+  ExtractConfig,
+  ExtractContext,
+  ProceduresFactory,
+  RPCConfig,
+  RPCHttpRouteDoc,
+} from '../../types.js'
 import { castArray } from 'es-toolkit/compat'
-import { ExpressFactoryItem, ExtractContext, ProceduresFactory } from './types.js'
+import { ExpressFactoryItem } from './types.js'
 
 export type { RPCConfig, RPCHttpRouteDoc }
 
@@ -122,7 +128,7 @@ export class ExpressRPCAppBuilder {
   private factories: ExpressFactoryItem<any>[] = []
 
   private _app: express.Express = express()
-  private _docs: RPCHttpRouteDoc[] = []
+  private _docs: (RPCHttpRouteDoc & object)[] = []
 
   get app(): express.Express {
     return this._app
@@ -137,14 +143,21 @@ export class ExpressRPCAppBuilder {
    * @param factory - The procedure factory created by Procedures<Context, RPCConfig>()
    * @param factoryContext - The context for procedure handlers. Can be a direct value,
    *                         a sync function (req) => Context, or an async function (req) => Promise<Context>
+   * @param extendProcedureDoc - A custom function to extend the generated RPC route documentation for each procedure.
    */
   register<TFactory extends ProceduresFactory>(
     factory: TFactory,
     factoryContext:
       | ExtractContext<TFactory>
-      | ((req: express.Request) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+      | ((req: express.Request) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
+    extendProcedureDoc?: (params: {
+      /* RPC App builder base http route doc */
+      base: RPCHttpRouteDoc
+      /* Procedure registration */
+      procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
+    }) => Record<string, any>
   ): this {
-    this.factories.push({ factory, factoryContext } as ExpressFactoryItem<any>)
+    this.factories.push({ factory, factoryContext, extendProcedureDoc } as ExpressFactoryItem<any>)
     return this
   }
 
@@ -153,9 +166,9 @@ export class ExpressRPCAppBuilder {
    * @return express.Application
    */
   build(): express.Application {
-    this.factories.forEach(({ factory, factoryContext }) => {
+    this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
       factory.getProcedures().map((procedure: TProcedureRegistration<any, RPCConfig>) => {
-        const route = this.buildRpcHttpRouteDoc(procedure)
+        const route = this.buildRpcHttpRouteDoc(procedure, extendProcedureDoc)
 
         this._docs.push(route)
 
@@ -198,14 +211,17 @@ export class ExpressRPCAppBuilder {
    * Generates the RPC HTTP route for the given procedure.
    * @param procedure
    */
-  private buildRpcHttpRouteDoc(procedure: TProcedureRegistration<any, RPCConfig>): RPCHttpRouteDoc {
+  private buildRpcHttpRouteDoc(
+    procedure: TProcedureRegistration<any, RPCConfig>,
+    extendProcedureDoc: ExpressFactoryItem['extendProcedureDoc']
+  ): RPCHttpRouteDoc {
     const { config } = procedure
     const path = ExpressRPCAppBuilder.makeRPCHttpRoutePath({
       name: procedure.name,
       config,
       prefix: this.config?.pathPrefix,
     })
-    const method = 'post' // RPCs use POST method
+    const method = 'post' as const // RPCs use POST method
     const jsonSchema: { body?: object; response?: object } = {}
 
     if (config.schema?.params) {
@@ -215,10 +231,23 @@ export class ExpressRPCAppBuilder {
       jsonSchema.response = config.schema.returnType
     }
 
-    return {
+    const base = {
+      name: procedure.name,
+      version: config.version,
+      scope: config.scope,
       path,
       method,
       jsonSchema,
     }
+    let extendedDoc: object = {}
+
+    if (extendProcedureDoc) {
+      extendedDoc = extendProcedureDoc({ base, procedure })
+    }
+
+    return {
+      ...extendedDoc,
+      ...base,
+    }
   }
 }

package/src/implementations/http/express-rpc/types.ts

@@ -1,33 +1,16 @@
-import { RPCConfig } from '../../types.js'
-import { Procedures } from '../../../index.js'
+import { ExtractConfig, ExtractContext, RPCConfig, RPCHttpRouteDoc } from '../../types.js'
+import { Procedures, TProcedureRegistration } from '../../../index.js'
 import express from 'express'
 
-/**
- * Extracts the TContext type from a Procedures factory return type.
- * Uses the first parameter of the handler function to infer the context type.
- */
-export type ExtractContext<TFactory> = TFactory extends {
-  getProcedures: () => Array<{ handler: (ctx: infer TContext, ...args: any[]) => any }>
-}
-  ? TContext
-  : never
-
-/**
- * Minimal structural type for a Procedures factory.
- * Uses explicit `any` types to avoid variance issues with generic constraints.
- */
-export type ProceduresFactory = {
-  getProcedures: () => Array<{
-    name: string
-    config: any
-    handler: (ctx: any, params?: any) => Promise<any>
-  }>
-  Create: (...args: any[]) => any
-}
-
 export type ExpressFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
   factory: TFactory
   factoryContext:
     | ExtractContext<TFactory>
     | ((req: express.Request) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+  extendProcedureDoc?: (params: {
+    /* RPC App builder base http route doc */
+    base: RPCHttpRouteDoc
+    /* Procedure registration */
+    procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
+  }) => Record<string, any>
 }

package/src/implementations/http/hono-rpc/README.md

@@ -30,8 +30,8 @@ RPC.Create(
     version: 1,
     schema: {
       params: v.object({ id: v.string() }),
-      returnType: v.object({ id: v.string(), name: v.string() })
-    }
+      returnType: v.object({ id: v.string(), name: v.string() }),
+    },
   },
   async (ctx, params) => {
     return { id: params.id, name: 'John Doe' }
@@ -39,10 +39,9 @@ RPC.Create(
 )
 
 // Build the Hono app
-const builder = new HonoRPCAppBuilder({ pathPrefix: '/rpc' })
-  .register(RPC, (c) => ({
-    userId: c.req.header('x-user-id') || 'anonymous'
-  }))
+const builder = new HonoRPCAppBuilder({ pathPrefix: '/rpc' }).register(RPC, (c) => ({
+  userId: c.req.header('x-user-id') || 'anonymous',
+}))
 
 const app = builder.build()
 
@@ -60,23 +59,27 @@ export default app
 
 ```typescript
 type HonoRPCAppBuilderConfig = {
-  app?: Hono                 // Existing Hono app (optional)
-  pathPrefix?: string        // Prefix for all routes (e.g., '/rpc/v1')
+  app?: Hono // Existing Hono app (optional)
+  pathPrefix?: string // Prefix for all routes (e.g., '/rpc/v1')
   onRequestStart?: (c: Context) => void
   onRequestEnd?: (c: Context) => void
   onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
-  error?: (procedure: TProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+  error?: (
+    procedure: TProcedureRegistration,
+    c: Context,
+    error: Error
+  ) => Response | Promise<Response>
 }
 ```
 
-| Option | Type | Description                                       |
-|--------|------|---------------------------------------------------|
-| `app` | `Hono` | Use existing Hono app instead of creating new one |
-| `pathPrefix` | `string` | Prefix all routes (e.g., `/rpc/v1`)               |
-| `onRequestStart` | `(c) => void` | Called at start of each request                   |
-| `onRequestEnd` | `(c) => void` | Called after handler completes                    |
-| `onSuccess` | `(proc, c) => void` | Called on successful handler execution            |
-| `error` | `(proc, c, err) => Response` | Custom error handler (must return Response)       |
+| Option           | Type                         | Description                                       |
+| ---------------- | ---------------------------- | ------------------------------------------------- |
+| `app`            | `Hono`                       | Use existing Hono app instead of creating new one |
+| `pathPrefix`     | `string`                     | Prefix all routes (e.g., `/rpc/v1`)               |
+| `onRequestStart` | `(c) => void`                | Called at start of each request                   |
+| `onRequestEnd`   | `(c) => void`                | Called after handler completes                    |
+| `onSuccess`      | `(proc, c) => void`          | Called on successful handler execution            |
+| `error`          | `(proc, c, err) => Response` | Custom error handler (must return Response)       |
 
 ## Context Resolution
 
@@ -86,7 +89,7 @@ The context resolver receives the Hono `Context` object:
 builder.register(RPC, (c: Context) => ({
   userId: c.req.header('x-user-id') || 'anonymous',
   userAgent: c.req.header('user-agent'),
-  ip: c.req.raw.headers.get('cf-connecting-ip')  // Cloudflare
+  ip: c.req.raw.headers.get('cf-connecting-ip'), // Cloudflare
 }))
 
 // Async context resolution
@@ -97,6 +100,41 @@ builder.register(RPC, async (c) => {
 })
 ```
 
+## Extending Procedure Documentation
+
+The `register` method accepts an optional third parameter `extendProcedureDoc` that allows you to add custom fields to each procedure's documentation. This is useful for adding metadata like descriptions, tags, or custom fields for API documentation generators.
+
+```typescript
+// Example of a factory extending the procedure config:
+type ExtendedRPCConfig = {
+  description: string
+  tags: string[]
+}
+
+builder.register(RPC, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }), {
+  extendProcedureDoc: ({ base, procedure }, { base: RPCHttpRouteDoc, procedure }) =>
+    ({
+      description: `Procedure: ${procedure.name}`,
+      tags: Array.isArray(procedure.config.scope)
+        ? procedure.config.scope
+        : [procedure.config.scope],
+    }),
+})
+
+// Access extended docs after build()
+const app = builder.build()
+console.log(builder.docs) // Each doc now includes description and tags
+```
+
+The `extendProcedureDoc` callback receives:
+
+| Parameter   | Type                     | Description                                                                                |
+| ----------- | ------------------------ | ------------------------------------------------------------------------------------------ |
+| `base`      | `RPCHttpRouteDoc`        | The base documentation with `name`, `path`, `method`, `scope`, `version`, and `jsonSchema` |
+| `procedure` | `TProcedureRegistration` | The full procedure registration including `name`, `config`, and `handler`                  |
+
+This allows you to derive documentation fields from procedure config or add static metadata per factory registration.
+
 ## Error Handling
 
 Custom error handler receives the procedure, context, and error. **Must return a Response:**
@@ -115,7 +153,7 @@ const builder = new HonoRPCAppBuilder({
     }
 
     return c.json({ error: 'Internal server error' }, 500)
-  }
+  },
 })
 ```
 
@@ -132,10 +170,9 @@ const app = new Hono()
 app.use('*', cors())
 app.get('/custom', (c) => c.json({ custom: true }))
 
-const builder = new HonoRPCAppBuilder({ app })
-  .register(RPC, contextResolver)
+const builder = new HonoRPCAppBuilder({ app }).register(RPC, contextResolver)
 
-builder.build()  // Adds RPC routes to existing app
+builder.build() // Adds RPC routes to existing app
 ```
 
 ## Runtime Compatibility
@@ -184,25 +221,25 @@ new HonoRPCAppBuilder(config?: HonoRPCAppBuilderConfig)
 
 ### Methods
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `register` | `register<T>(factory, context): this` | Register procedure factory with context |
-| `build` | `build(): Hono` | Build routes and return app |
-| `makeRPCHttpRoutePath` | `makeRPCHttpRoutePath(config: RPCConfig): string` | Generate route path |
+| Method                 | Signature                                         | Description                                                        |
+| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
+| `register`             | `register<T>(factory, context, options?): this`   | Register procedure factory with context and optional doc extension |
+| `build`                | `build(): Hono`                                   | Build routes and return app                                        |
+| `makeRPCHttpRoutePath` | `makeRPCHttpRoutePath(config: RPCConfig): string` | Generate route path                                                |
 
 ### Static Methods
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
+| Method                 | Signature                                                 | Description                            |
+| ---------------------- | --------------------------------------------------------- | -------------------------------------- |
 | `makeRPCHttpRoutePath` | `static makeRPCHttpRoutePath({ config, prefix }): string` | Generate route path with custom prefix |
 
 ### Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `app` | `Hono` | The Hono application instance |
-| `docs` | `RPCHttpRouteDoc[]` | Route documentation (after `build()`) |
-| `config` | `HonoRPCAppBuilderConfig` | The configuration object |
+| Property | Type                      | Description                           |
+| -------- | ------------------------- | ------------------------------------- |
+| `app`    | `Hono`                    | The Hono application instance         |
+| `docs`   | `RPCHttpRouteDoc[]`       | Route documentation (after `build()`) |
+| `config` | `HonoRPCAppBuilderConfig` | The configuration object              |
 
 ## TypeScript Types
 
@@ -211,7 +248,7 @@ import {
   HonoRPCAppBuilder,
   HonoRPCAppBuilderConfig,
   RPCConfig,
-  RPCHttpRouteDoc
+  RPCHttpRouteDoc,
 } from 'ts-procedures/hono-rpc'
 ```
 
@@ -233,11 +270,11 @@ const AuthRPC = Procedures<AuthContext, RPCConfig>()
 
 // Public procedures
 PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({
-  status: 'ok'
+  status: 'ok',
 }))
 
 PublicRPC.Create('GetVersion', { scope: ['system', 'version'], version: 1 }, async () => ({
-  version: '1.0.0'
+  version: '1.0.0',
 }))
 
 // Authenticated procedures
@@ -246,7 +283,7 @@ AuthRPC.Create(
   {
     scope: ['users', 'profile'],
     version: 1,
-    schema: { returnType: v.object({ userId: v.string() }) }
+    schema: { returnType: v.object({ userId: v.string() }) },
   },
   async (ctx) => ({ userId: ctx.userId })
 )
@@ -256,7 +293,7 @@ AuthRPC.Create(
   {
     scope: ['users', 'profile'],
     version: 2,
-    schema: { params: v.object({ name: v.string() }) }
+    schema: { params: v.object({ name: v.string() }) },
   },
   async (ctx, params) => ({ userId: ctx.userId, name: params.name })
 )
@@ -270,14 +307,14 @@ const builder = new HonoRPCAppBuilder({
   onError: (proc, c, err) => {
     console.error(`✗ ${proc.name}:`, err.message)
     return c.json({ error: err.message }, 500)
-  }
+  },
 })
 
 builder
   .register(PublicRPC, () => ({ source: 'public' as const }))
   .register(AuthRPC, (c) => ({
     source: 'auth' as const,
-    userId: c.req.header('x-user-id') || 'anonymous'
+    userId: c.req.header('x-user-id') || 'anonymous',
   }))
 
 const app = builder.build()
@@ -288,6 +325,9 @@ const app = builder.build()
 // POST /rpc/users/profile/get-user/1
 // POST /rpc/users/profile/get-user/2
 
-console.log('Routes:', builder.docs.map(d => d.path))
+console.log(
+  'Routes:',
+  builder.docs.map((d) => d.path)
+)
 export default app
 ```

package/src/implementations/http/hono-rpc/index.test.ts

@@ -724,6 +724,231 @@ describe('HonoRPCAppBuilder', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // extendProcedureDoc Tests
+  // --------------------------------------------------------------------------
+  describe('extendProcedureDoc', () => {
+    test('adds custom properties to generated documentation', () => {
+      const builder = new HonoRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('GetUser', { scope: 'users', version: 1 }, async () => ({ name: 'test' }))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ base, procedure }) => ({
+          summary: `Get user endpoint`,
+          tags: ['users'],
+          operationId: procedure.name,
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc).toHaveProperty('summary', 'Get user endpoint')
+      expect(doc).toHaveProperty('tags', ['users'])
+      expect(doc).toHaveProperty('operationId', 'GetUser')
+    })
+
+    test('receives correct base and procedure parameters', () => {
+      const extendFn = vi.fn(() => ({}))
+      const builder = new HonoRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      const paramsSchema = v.object({ id: v.string() })
+      RPC.Create(
+        'GetItem',
+        { scope: 'items', version: 2, schema: { params: paramsSchema } },
+        async () => ({})
+      )
+
+      builder.register(RPC, () => ({}), extendFn)
+      builder.build()
+
+      expect(extendFn).toHaveBeenCalledTimes(1)
+      const callArg = extendFn.mock.calls[0]![0 as any] as any
+
+      // Verify base properties
+      expect(callArg.base).toHaveProperty('name', 'GetItem')
+      expect(callArg.base).toHaveProperty('version', 2)
+      expect(callArg.base).toHaveProperty('scope', 'items')
+      expect(callArg.base).toHaveProperty('path', '/items/get-item/2')
+      expect(callArg.base).toHaveProperty('method', 'post')
+      expect(callArg.base.jsonSchema).toHaveProperty('body')
+
+      // Verify procedure properties
+      expect(callArg.procedure).toHaveProperty('name', 'GetItem')
+      expect(callArg.procedure).toHaveProperty('handler')
+      expect(callArg.procedure.config).toHaveProperty('scope', 'items')
+      expect(callArg.procedure.config).toHaveProperty('version', 2)
+    })
+
+    test('base properties take precedence over extended properties', () => {
+      const builder = new HonoRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        () => ({
+          name: 'OverriddenName',
+          path: '/overridden/path',
+          method: 'get',
+          customField: 'custom-value',
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0]!
+      // Base properties should NOT be overridden
+      expect(doc.name).toBe('Test')
+      expect(doc.path).toBe('/test/test/1')
+      expect(doc.method).toBe('post')
+      // Custom field should be present
+      expect(doc).toHaveProperty('customField', 'custom-value')
+    })
+
+    test('different factories can have different extendProcedureDoc functions', () => {
+      const builder = new HonoRPCAppBuilder()
+
+      const PublicRPC = Procedures<{}, RPCConfig>()
+      const AdminRPC = Procedures<{}, RPCConfig>()
+
+      PublicRPC.Create('GetPublic', { scope: 'public', version: 1 }, async () => ({}))
+      AdminRPC.Create('GetAdmin', { scope: 'admin', version: 1 }, async () => ({}))
+
+      builder
+        .register(
+          PublicRPC,
+          () => ({}),
+          () => ({
+            security: [],
+            tags: ['public'],
+          })
+        )
+        .register(
+          AdminRPC,
+          () => ({}),
+          () => ({
+            security: [{ bearerAuth: [] }],
+            tags: ['admin'],
+          })
+        )
+
+      builder.build()
+
+      const publicDoc = builder.docs.find((d) => d.name === 'GetPublic')!
+      const adminDoc = builder.docs.find((d) => d.name === 'GetAdmin')!
+
+      expect(publicDoc).toHaveProperty('security', [])
+      expect(publicDoc).toHaveProperty('tags', ['public'])
+      expect(adminDoc).toHaveProperty('security', [{ bearerAuth: [] }])
+      expect(adminDoc).toHaveProperty('tags', ['admin'])
+    })
+
+    test('extendProcedureDoc is called for each procedure in factory', () => {
+      const extendFn = vi.fn(() => ({ extended: true }))
+      const builder = new HonoRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Method1', { scope: 'm1', version: 1 }, async () => ({}))
+      RPC.Create('Method2', { scope: 'm2', version: 1 }, async () => ({}))
+      RPC.Create('Method3', { scope: 'm3', version: 1 }, async () => ({}))
+
+      builder.register(RPC, () => ({}), extendFn)
+      builder.build()
+
+      expect(extendFn).toHaveBeenCalledTimes(3)
+
+      const procedureNames = extendFn.mock.calls.map((call: any) => call[0].procedure.name)
+      expect(procedureNames).toContain('Method1')
+      expect(procedureNames).toContain('Method2')
+      expect(procedureNames).toContain('Method3')
+    })
+
+    test('not providing extendProcedureDoc results in base documentation only', () => {
+      const builder = new HonoRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
+
+      builder.register(RPC, () => ({})) // No extendProcedureDoc
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc.name).toBe('Test')
+      expect(doc.path).toBe('/test/test/1')
+      expect(doc.method).toBe('post')
+      // Should not have any extra properties
+      expect(Object.keys(doc)).toEqual(['name', 'version', 'scope', 'path', 'method', 'jsonSchema'])
+    })
+
+    test('extendProcedureDoc can access procedure config for conditional logic', () => {
+      const builder = new HonoRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('PublicEndpoint', { scope: 'public', version: 1 }, async () => ({}))
+      RPC.Create('PrivateEndpoint', { scope: 'private', version: 1 }, async () => ({}))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ procedure }) => ({
+          isPublic: procedure.config.scope === 'public',
+          description: `This is a ${procedure.config.scope} endpoint`,
+        })
+      )
+      builder.build()
+
+      const publicDoc = builder.docs.find((d) => d.name === 'PublicEndpoint')!
+      const privateDoc = builder.docs.find((d) => d.name === 'PrivateEndpoint')!
+
+      expect(publicDoc).toHaveProperty('isPublic', true)
+      expect(publicDoc).toHaveProperty('description', 'This is a public endpoint')
+      expect(privateDoc).toHaveProperty('isPublic', false)
+      expect(privateDoc).toHaveProperty('description', 'This is a private endpoint')
+    })
+
+    test('extendProcedureDoc can use base jsonSchema for OpenAPI-style docs', () => {
+      const builder = new HonoRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      const paramsSchema = v.object({ userId: v.string() })
+      const returnSchema = v.object({ name: v.string(), email: v.string() })
+
+      RPC.Create(
+        'GetUser',
+        { scope: 'users', version: 1, schema: { params: paramsSchema, returnType: returnSchema } },
+        async () => ({ name: 'test', email: 'test@example.com' })
+      )
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ base }) => ({
+          requestBody: base.jsonSchema.body
+            ? { content: { 'application/json': { schema: base.jsonSchema.body } } }
+            : undefined,
+          responses: {
+            200: base.jsonSchema.response
+              ? { content: { 'application/json': { schema: base.jsonSchema.response } } }
+              : { description: 'Success' },
+          },
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0] as any
+      expect(doc).toHaveProperty('requestBody')
+      expect(doc.requestBody).toHaveProperty('content')
+      expect(doc).toHaveProperty('responses')
+      expect(doc.responses).toHaveProperty('200')
+    })
+  })
+
   // --------------------------------------------------------------------------
   // Integration Test
   // --------------------------------------------------------------------------