@pikku/cli 0.9.16-next.0 → 0.10.0

package/.pikku/function/pikku-function-types.gen.ts

@@ -1,24 +1,27 @@
 /**
- * This file was generated by the @pikku/cli
+ * This file was generated by @pikku/cli@0.10.0
  */
 /**
- * This file was generated by the @pikku/cli
  * Core function, middleware, and permission types for all wirings
  */
 
-import { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuMiddleware, addMiddleware as addMiddlewareCore, addPermission as addPermissionCore } from '@pikku/core'
+import { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuMiddleware, CorePermissionGroup, addMiddleware as addMiddlewareCore, addPermission as addPermissionCore } from '@pikku/core'
 import { CorePikkuFunction, CorePikkuFunctionSessionless } from '@pikku/core/function'
-import { PikkuChannel, PikkuMCP } from '@pikku/core'
+import { PikkuChannel } from '@pikku/core/channel'
+import { PikkuMCP } from '@pikku/core/mcp'
 
 import type { UserSession } from '../../types/application-types.d.js'
 import type { SingletonServices } from '../../types/application-types.d.js'
 import type { Services } from '../../types/application-types.d.js'
+import type { Config } from '../../types/application-types.d.js'
 import type { TypedPikkuRPC } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js'
+import type { RequiredSingletonServices, RequiredSessionServices } from '../pikku-services.gen.js'
 
 
 
 type Session = UserSession
 
+
 /**
  * Type-safe API permission definition that integrates with your application's session type.
  * Use this to define authorization logic for your API endpoints.
@@ -36,35 +39,84 @@ export type PikkuPermission<In = unknown, RequiredServices extends Services = Se
  */
 export type PikkuMiddleware<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuMiddleware<RequiredServices, Session>
 
+/**
+ * Configuration object for creating a permission with metadata
+ */
+export type PikkuPermissionConfig<In = unknown, RequiredServices extends Services = Services> = {
+  /** The permission function */
+  func: PikkuPermission<In, RequiredServices>
+  /** Optional human-readable name for the permission */
+  name?: string
+  /** Optional description of what the permission checks */
+  description?: string
+}
+
 /**
  * Factory function for creating permissions with tree-shaking support.
- * This enables the bundler to detect which services your permission actually uses.
+ * Supports both direct function and configuration object syntax.
  *
  * @example
  * ```typescript
+ * // Direct function syntax
  * const permission = pikkuPermission(({ logger }, data, session) => {
- *   return session?.isAdmin || false
+ *   return session?.role === 'admin'
+ * })
+ *
+ * // Configuration object syntax with metadata
+ * const adminPermission = pikkuPermission({
+ *   name: 'Admin Permission',
+ *   description: 'Checks if user has admin role',
+ *   func: async ({ logger }, data, session) => {
+ *     return session?.role === 'admin'
+ *   }
  * })
  * ```
  */
-export const pikkuPermission = <In>(func: PikkuPermission<In>) => {
-  return func
+export const pikkuPermission = <In>(
+  permission: PikkuPermission<In> | PikkuPermissionConfig<In>
+): PikkuPermission<In> => {
+  return typeof permission === 'function' ? permission : permission.func
+}
+
+/**
+ * Configuration object for creating middleware with metadata
+ */
+export type PikkuMiddlewareConfig<RequiredServices extends SingletonServices = SingletonServices> = {
+  /** The middleware function */
+  func: PikkuMiddleware<RequiredServices>
+  /** Optional human-readable name for the middleware */
+  name?: string
+  /** Optional description of what the middleware does */
+  description?: string
 }
 
 /**
  * Factory function for creating middleware with tree-shaking support.
- * This enables the bundler to detect which services your middleware actually uses.
+ * Supports both direct function and configuration object syntax.
  *
  * @example
  * ```typescript
+ * // Direct function syntax
  * const middleware = pikkuMiddleware(({ logger }, interactions, next) => {
  *   logger.info('Middleware executed')
  *   await next()
  * })
+ *
+ * // Configuration object syntax with metadata
+ * const logMiddleware = pikkuMiddleware({
+ *   name: 'Request Logger',
+ *   description: 'Logs all incoming requests',
+ *   func: async ({ logger }, interactions, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * })
  * ```
  */
-export const pikkuMiddleware = (func: PikkuMiddleware) => {
-  return func
+export const pikkuMiddleware = <RequiredServices extends SingletonServices = SingletonServices>(
+  middleware: PikkuMiddleware<RequiredServices> | PikkuMiddlewareConfig<RequiredServices>
+): PikkuMiddleware<RequiredServices> => {
+  return typeof middleware === 'function' ? middleware : middleware.func
 }
 
 /**
@@ -90,6 +142,31 @@ export const pikkuMiddlewareFactory = <In = any>(
   return factory
 }
 
+/**
+ * Factory function for creating permission factories
+ * Use this when your permission needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
+ *   role
+ * }) => {
+ *   return pikkuPermission(async ({ logger }, data, session) => {
+ *     if (!session || session.role !== role) {
+ *       logger.warn(`Permission denied: required role '${role}'`)
+ *       return false
+ *     }
+ *     return true
+ *   })
+ * })
+ * ```
+ */
+export const pikkuPermissionFactory = <In = any>(
+  factory: (input: In) => PikkuPermission<any>
+): ((input: In) => PikkuPermission<any>) => {
+  return factory
+}
+
 /**
  * A sessionless API function that doesn't require user authentication.
  * Use this for public endpoints, health checks, or operations that don't need user context.
@@ -105,7 +182,7 @@ export type PikkuFunctionSessionless<
   Out = never,
   ChannelData = null,  // null means optional channel
   MCPData = null, // null means optional MCP
-  RequiredServices extends Services = Services &
+  RequiredServices extends Services = Omit<Services, 'rpc' | 'channel' | 'mcp'> &
     { rpc: TypedPikkuRPC } & (
     [ChannelData] extends [null]
       ? { channel?: PikkuChannel<unknown, Out> }  // Optional channel
@@ -131,7 +208,7 @@ export type PikkuFunction<
   Out = never,
   ChannelData = null,  // null means optional channel
   MCPData = null, // null means optional MCP
-  RequiredServices extends Services = Omit<Services, 'rpc'> &
+  RequiredServices extends Services = Omit<Services, 'rpc' | 'channel' | 'mcp'> &
     { rpc: TypedPikkuRPC } & (
     [ChannelData] extends [null]
       ? { channel?: PikkuChannel<unknown, Out> }  // Optional channel
@@ -148,12 +225,16 @@ export type PikkuFunction<
  *
  * @template In - The input type
  * @template Out - The output type
+ * @template ChannelData - Channel data type
+ * @template MCPData - MCP data type
  * @template PikkuFunc - The function type (can be narrowed to PikkuFunction or PikkuFunctionSessionless)
  */
 export type PikkuFunctionConfig<
   In = unknown,
   Out = unknown,
-  PikkuFunc extends PikkuFunction<In, Out> | PikkuFunctionSessionless<In, Out> = PikkuFunction<In, Out> | PikkuFunctionSessionless<In, Out>
+  ChannelData = unknown,
+  MCPData = unknown,
+  PikkuFunc extends PikkuFunction<In, Out, ChannelData, MCPData> | PikkuFunctionSessionless<In, Out, ChannelData, MCPData> = PikkuFunction<In, Out, ChannelData, MCPData> | PikkuFunctionSessionless<In, Out, ChannelData, MCPData>
 > = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware>
 
 /**
@@ -180,7 +261,7 @@ export type PikkuFunctionConfig<
 export const pikkuFunc = <In, Out = unknown>(
   func:
     | PikkuFunction<In, Out>
-    | CorePikkuFunctionConfig<PikkuFunction<In, Out>, PikkuPermission<In>>
+    | CorePikkuFunctionConfig<PikkuFunction<In, Out>, PikkuPermission<In>, PikkuMiddleware>
 ) => {
   return typeof func === 'function' ? { func } : func
 }
@@ -237,6 +318,73 @@ export const pikkuVoidFunc = (
   return typeof func === 'function' ? { func } : func
 }
 
+/**
+ * Creates a Pikku config factory.
+ * Use this to define your application's configuration factory.
+ *
+ * @param func - Config factory function that returns your application's config
+ * @returns The config factory function
+ *
+ * @example
+ * ```typescript
+ * export const createConfig = pikkuConfig(async () => {
+ *   return {
+ *     apiUrl: process.env.API_URL || 'http://localhost:3000',
+ *     dbUrl: process.env.DATABASE_URL
+ *   }
+ * })
+ * ```
+ */
+export const pikkuConfig = (
+  func: (variables?: any, ...args: any[]) => Promise<Config>
+) => func
+
+/**
+ * Creates a Pikku singleton services factory.
+ * Use this to define services that are created once and shared across all requests.
+ *
+ * @param func - Singleton services factory function
+ * @returns The singleton services factory function
+ *
+ * @example
+ * ```typescript
+ * export const createSingletonServices = pikkuServices(async (config, existingServices) => {
+ *   return {
+ *     config,
+ *     logger: new CustomLogger(),
+ *     db: await createDatabaseConnection(config.dbUrl)
+ *   }
+ * })
+ * ```
+ */
+export const pikkuServices = (
+  func: (config: Config, existingServices?: Partial<SingletonServices>) => Promise<RequiredSingletonServices>
+) => func
+
+/**
+ * Creates a Pikku session services factory.
+ * Use this to define services that are created per-request/session.
+ *
+ * @param func - Session services factory function
+ * @returns The session services factory function
+ *
+ * @example
+ * ```typescript
+ * export const createSessionServices = pikkuSessionServices(async (services, interaction, session) => {
+ *   return {
+ *     userCache: new UserCache(session?.userId)
+ *   }
+ * })
+ * ```
+ */
+export const pikkuSessionServices = (
+  func: (
+    services: SingletonServices,
+    interaction: any,
+    session: Session | undefined
+  ) => Promise<RequiredSessionServices>
+) => func
+
 /**
  * Adds global middleware for a specific tag.
  *
@@ -271,7 +419,7 @@ export const addMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
  * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
  *
  * @param tag - The tag that the permissions should apply to.
- * @param permissions - The permissions array to apply for the specified tag.
+ * @param permissions - The permissions array or object to apply for the specified tag.
  *
  * @throws Error if permissions for the tag already exist.
  *
@@ -283,10 +431,10 @@ export const addMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
  * // Add authentication permissions for auth endpoints
  * addPermission('auth', [authPermission])
  *
- * // Add read permissions for all API endpoints
- * addPermission('api', [readPermission])
+ * // Add read permissions for all API endpoints (as object)
+ * addPermission('api', { read: readPermission })
  * ```
  */
-export const addPermission = <In = unknown>(tag: string, permissions: PikkuPermission<In>[]) => {
+export const addPermission = <In = unknown>(tag: string, permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
   addPermissionCore(tag, permissions as any)
 }