@pikku/core 0.12.2 → 0.12.4

package/src/function/function-runner.ts

@@ -1,365 +0,0 @@
-import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
-import {
-  combineChannelMiddleware,
-  wrapChannelWithMiddleware,
-} from '../wirings/channel/channel-middleware-runner.js'
-import { runPermissions } from '../permissions.js'
-import { pikkuState } from '../pikku-state.js'
-import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
-import type {
-  CoreServices,
-  CoreUserSession,
-  CorePikkuMiddleware,
-  PikkuWiringTypes,
-  PikkuWire,
-  MiddlewareMetadata,
-  PermissionMetadata,
-  CoreSingletonServices,
-  CreateWireServices,
-  CoreConfig,
-} from '../types/core.types.js'
-import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
-import type {
-  CorePermissionGroup,
-  CorePikkuFunctionConfig,
-  CorePikkuPermission,
-} from './functions.types.js'
-import { parseVersionedId } from '../version.js'
-import type { SessionService } from '../services/user-session-service.js'
-import { createFunctionSessionWireProps } from '../services/user-session-service.js'
-import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
-import { rpcService } from '../wirings/rpc/rpc-runner.js'
-import { closeWireServices } from '../utils.js'
-
-/**
- * Get or create singleton services for an addon package.
- * Services are cached in pikkuState to avoid recreation on each call.
- *
- * @param packageName - The addon package name
- * @param parentServices - The parent/caller's singleton services (used as base)
- * @returns The package's singleton services
- */
-const getOrCreatePackageSingletonServices = async (
-  packageName: string,
-  parentServices: CoreSingletonServices
-): Promise<CoreSingletonServices> => {
-  // Check if we already have cached singleton services for this package
-  const cachedServices = pikkuState(packageName, 'package', 'singletonServices')
-  if (cachedServices) {
-    return cachedServices
-  }
-
-  // Get the package's service factories
-  const factories = pikkuState(packageName, 'package', 'factories')
-  if (!factories || !factories.createSingletonServices) {
-    // No factories registered, use parent services
-    return parentServices
-  }
-
-  // Create config for the package (use parent config if no factory)
-  let config: CoreConfig = parentServices.config
-  if (factories.createConfig) {
-    config = await factories.createConfig(parentServices.variables)
-  }
-
-  // Create singleton services for the package, passing parent services as existing
-  const packageServices = await factories.createSingletonServices(
-    config,
-    parentServices
-  )
-
-  // Cache the services
-  pikkuState(packageName, 'package', 'singletonServices', packageServices)
-
-  return packageServices
-}
-
-export const addFunction = (
-  funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>,
-  packageName: string | null = null
-) => {
-  pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
-}
-
-export const getFunctionNames = (
-  packageName: string | null = null
-): string[] => {
-  const functionsMeta = pikkuState(packageName, 'function', 'meta')
-  return Object.keys(functionsMeta)
-}
-
-export const getAllFunctionNames = (): string[] => {
-  const functions: string[] = []
-
-  const mainFunctionsMeta = pikkuState(null, 'function', 'meta')
-  functions.push(...Object.keys(mainFunctionsMeta))
-
-  const addons = pikkuState(null, 'rpc', 'addons')
-  for (const [namespace, config] of addons) {
-    const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta')
-    for (const funcName of Object.keys(packageFunctionsMeta)) {
-      functions.push(`${namespace}:${funcName}`)
-    }
-  }
-
-  return functions
-}
-
-export const runPikkuFuncDirectly = async <In, Out>(
-  funcName: string,
-  allServices: CoreServices,
-  wire: PikkuWire,
-  data: In,
-  userSession?: SessionService<CoreUserSession>,
-  packageName: string | null = null
-) => {
-  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
-    funcName
-  )
-  if (!funcConfig) {
-    throw new Error(`Function not found: ${funcName}`)
-  }
-  const wireWithSession = {
-    ...wire,
-    ...(userSession && createFunctionSessionWireProps(userSession)),
-  }
-  return (await funcConfig.func(allServices, data, wireWithSession)) as Out
-}
-
-export const runPikkuFunc = async <In = any, Out = any>(
-  wireType: PikkuWiringTypes,
-  wireId: string,
-  funcName: string,
-  {
-    singletonServices,
-    createWireServices,
-    data,
-    auth: wiringAuth,
-    inheritedMiddleware,
-    wireMiddleware,
-    inheritedChannelMiddleware,
-    wireChannelMiddleware,
-    inheritedPermissions,
-    wirePermissions,
-    coerceDataFromSchema,
-    tags = [],
-    wire,
-    sessionService,
-    packageName = null,
-  }: {
-    singletonServices: CoreSingletonServices
-    createWireServices?: CreateWireServices
-    data: () => Promise<In> | In
-    auth?: boolean
-    inheritedMiddleware?: MiddlewareMetadata[]
-    wireMiddleware?: CorePikkuMiddleware[]
-    inheritedChannelMiddleware?: MiddlewareMetadata[]
-    wireChannelMiddleware?: CorePikkuChannelMiddleware[]
-    inheritedPermissions?: PermissionMetadata[]
-    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
-    coerceDataFromSchema?: boolean
-    tags?: string[]
-    wire: PikkuWire
-    sessionService?: SessionService<CoreUserSession>
-    packageName?: string | null
-  }
-): Promise<Out> => {
-  wire.wireType ??= wireType
-  wire.wireId ??= wireId
-
-  const funcMap = pikkuState(packageName, 'function', 'functions')
-  let funcConfig = funcMap.get(funcName)
-  const allMeta = pikkuState(packageName, 'function', 'meta')
-  let funcMeta = allMeta[funcName]
-
-  if (!funcConfig || !funcMeta) {
-    const { baseName, version } = parseVersionedId(funcName)
-    if (version !== null) {
-      funcConfig = funcConfig || funcMap.get(baseName)
-      funcMeta = funcMeta || allMeta[baseName]
-      if (funcConfig && funcMeta) {
-        singletonServices.logger.warn(
-          `Version '${funcName}' not registered, resolved to '${baseName}'`
-        )
-      }
-    }
-  }
-
-  if (!funcConfig) {
-    throw new Error(`Function not found: ${funcName}`)
-  }
-  if (!funcMeta) {
-    throw new Error(`Function meta not found: ${funcName}`)
-  }
-
-  // For addon packages, get or create their singleton services
-  const resolvedSingletonServices = packageName
-    ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
-    : singletonServices
-
-  // Get the package's createWireServices if available
-  let resolvedCreateWireServices = createWireServices
-  if (packageName) {
-    const factories = pikkuState(packageName, 'package', 'factories')
-    if (factories?.createWireServices) {
-      resolvedCreateWireServices = factories.createWireServices
-    }
-  }
-
-  const allChannelMiddleware = combineChannelMiddleware(wireType, wireId, {
-    wireInheritedChannelMiddleware: inheritedChannelMiddleware,
-    wireChannelMiddleware,
-    packageName,
-  })
-
-  const resolvedWire =
-    allChannelMiddleware.length > 0 && wire.channel
-      ? wrapChannelWithMiddleware(
-          wire,
-          resolvedSingletonServices,
-          allChannelMiddleware
-        )
-      : wire
-
-  // Convert tags to PermissionMetadata and merge with inheritedPermissions
-  let mergedInheritedPermissions: PermissionMetadata[]
-  if (tags && tags.length > 0) {
-    mergedInheritedPermissions = [
-      ...(inheritedPermissions || []),
-      ...tags.map((tag) => ({ type: 'tag' as const, tag })),
-    ]
-  } else {
-    mergedInheritedPermissions = inheritedPermissions || []
-  }
-
-  // Helper function to run permissions and execute the function
-  const executeFunction = async () => {
-    if (sessionService) {
-      resolvedWire.session = sessionService.freezeInitial()
-      resolvedWire.setSession = (s: any) => sessionService.set(s)
-      resolvedWire.clearSession = () => sessionService.clear()
-      resolvedWire.getSession = () => sessionService.get()
-      resolvedWire.hasSessionChanged = () => sessionService.sessionChanged
-    }
-
-    const session = resolvedWire.session
-
-    if (funcMeta.sessionless) {
-      if (wiringAuth === true || funcConfig.auth === true) {
-        if (!session) {
-          throw new ForbiddenError('Authentication required')
-        }
-      }
-    } else if (funcMeta.sessionless === false) {
-      if (wiringAuth === false || funcConfig.auth === false) {
-        resolvedSingletonServices.logger.warn(
-          `Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`
-        )
-      }
-      if (!session) {
-        throw new ForbiddenError('Authentication required')
-      }
-    } else {
-      // TODO: Remove after a couple of releases — backward compat for
-      // generated metadata that doesn't include the `sessionless` field yet.
-      if (wiringAuth === true || funcConfig.auth === true) {
-        if (!session) {
-          throw new ForbiddenError('Authentication required')
-        }
-      }
-    }
-
-    if ((session as any)?.readonly && !funcMeta.readonly) {
-      throw new ReadonlySessionError()
-    }
-
-    // Evaluate the data from the lazy function
-    const actualData = await data()
-
-    // Validate and coerce data if schema is defined
-    const inputSchemaName = funcMeta.inputSchemaName
-    if (inputSchemaName) {
-      // Validate request data against the defined schema, if any
-      await validateSchema(
-        resolvedSingletonServices.logger,
-        resolvedSingletonServices.schema,
-        inputSchemaName,
-        actualData,
-        packageName
-      )
-      // Coerce (top level) query string parameters or date objects if specified by the schema
-      if (coerceDataFromSchema) {
-        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
-      }
-    }
-
-    if (
-      mergedInheritedPermissions.length > 0 ||
-      wirePermissions ||
-      funcMeta.permissions ||
-      funcConfig.permissions
-    ) {
-      await runPermissions(wireType, wireId, {
-        wireInheritedPermissions: mergedInheritedPermissions,
-        wirePermissions: wirePermissions,
-        funcInheritedPermissions: funcMeta.permissions,
-        funcPermissions: funcConfig.permissions,
-        services: resolvedSingletonServices,
-        wire: resolvedWire as any,
-        data: actualData,
-        packageName,
-      })
-    }
-
-    const wireServices = await resolvedCreateWireServices?.(
-      resolvedSingletonServices,
-      resolvedWire
-    )
-    try {
-      const services =
-        wireServices && Object.keys(wireServices).length > 0
-          ? { ...resolvedSingletonServices, ...wireServices }
-          : resolvedSingletonServices
-      Object.defineProperty(resolvedWire, 'rpc', {
-        get() {
-          const rpc = rpcService.getContextRPCService(services, resolvedWire, {
-            sessionService,
-          })
-          Object.defineProperty(resolvedWire, 'rpc', {
-            value: rpc,
-            writable: true,
-            configurable: true,
-          })
-          return rpc
-        },
-        configurable: true,
-        enumerable: true,
-      })
-      return await funcConfig.func(services, actualData, resolvedWire)
-    } finally {
-      if (wireServices && Object.keys(wireServices).length > 0) {
-        await closeWireServices(resolvedSingletonServices.logger, wireServices)
-      }
-    }
-  }
-
-  const allMiddleware = combineMiddleware(wireType, wireId, {
-    wireInheritedMiddleware: inheritedMiddleware,
-    wireMiddleware,
-    funcInheritedMiddleware: funcMeta.middleware,
-    funcMiddleware: funcConfig.middleware,
-    packageName,
-  })
-
-  if (allMiddleware.length > 0) {
-    return (await runMiddleware<CorePikkuMiddleware>(
-      resolvedSingletonServices,
-      resolvedWire,
-      allMiddleware,
-      executeFunction
-    )) as Out
-  }
-
-  return (await executeFunction()) as Out
-}

package/src/function/functions.types.ts

@@ -1,267 +0,0 @@
-import type {
-  CoreServices,
-  CoreSingletonServices,
-  CoreUserSession,
-  CorePikkuMiddleware,
-  PikkuWire,
-  PickRequired,
-} from '../types/core.types.js'
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { CoreNodeConfig } from '../wirings/node/node.types.js'
-
-/**
- * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
- * This alias exists only for backward compatibility with generated code.
- */
-export type ZodLike<T = any> = StandardSchemaV1<T, T>
-
-/**
- * Represents a core API function that performs an operation using core services and a user session.
- *
- * @template In - The input type.
- * @template Out - The output type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
- */
-export type CorePikkuFunction<
-  In,
-  Out,
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-  Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>,
-> = (
-  services: Services,
-  data: In,
-  wire: Wire
-) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
-
-/**
- * Represents a core API function that can be used without a session.
- *
- * @template In - The input type.
- * @template Out - The output type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
- */
-export type CorePikkuFunctionSessionless<
-  In,
-  Out,
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-  Wire extends PikkuWire<In, Out, false, Session, any, any, any> = PikkuWire<
-    In,
-    Out,
-    false,
-    Session,
-    any,
-    any,
-    any
-  >,
-> = (
-  services: Services,
-  data: In,
-  wire: Wire
-) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
-
-/**
- * Represents a function that checks permissions for a given operation.
- *
- * @template In - The input type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
-export type CorePikkuPermission<
-  In = any,
-  Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<
-    In,
-    never,
-    false,
-    CoreUserSession,
-    any,
-    never,
-    never
-  > = PikkuWire<In, never, false, CoreUserSession, never, never, never>,
-> = (services: Services, data: In, wire: Wire) => Promise<boolean>
-
-/**
- * Configuration object for creating a permission with metadata
- *
- * @template In - The input type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
-export type CorePikkuPermissionConfig<
-  In = any,
-  Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
-    In,
-    never,
-    false,
-    CoreUserSession
-  >,
-> = {
-  /** The permission function */
-  func: CorePikkuPermission<In, Services, Wire>
-  /** 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
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * )
- *
- * // Configuration object syntax with metadata
- * export const adminPermission = pikkuPermission({
- *   name: 'Admin Permission',
- *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * })
- * ```
- */
-export const pikkuPermission = <
-  In = any,
-  Services extends CoreSingletonServices = CoreServices,
-  Wire extends PickRequired<
-    PikkuWire<In, never, false, CoreUserSession>,
-    'session'
-  > = PickRequired<PikkuWire<In, never, false, CoreUserSession>, 'session'>,
->(
-  permission:
-    | CorePikkuPermission<In, Services, Wire>
-    | CorePikkuPermissionConfig<In, Services, Wire>
-): CorePikkuPermission<In, Services, Wire> => {
-  return typeof permission === 'function' ? permission : permission.func
-}
-
-/**
- * A factory function that takes input and returns a permission
- * Used when permissions need configuration/input parameters
- *
- * @template In - The input type for the factory.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
-export type CorePikkuPermissionFactory<
-  In = any,
-  Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
-    In,
-    never,
-    false,
-    CoreUserSession
-  >,
-> = (input: In) => CorePikkuPermission<any, Services, Wire>
-
-/**
- * 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, { getSession }) => {
- *      const currentSession = await getSession()
- *     if (!currentSession || currentSession.role !== role) {
- *       logger.warn(`Permission denied: required role '${role}'`)
- *       return false
- *     }
- *     return true
- *   })
- * })
- * ```
- */
-export const pikkuPermissionFactory = <In = any>(
-  factory: CorePikkuPermissionFactory<In>
-): CorePikkuPermissionFactory<In> => {
-  return factory
-}
-
-export type CorePikkuAuth<
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = (services: Services, session: Session) => Promise<boolean> | boolean
-
-export type CorePikkuAuthConfig<
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = {
-  func: CorePikkuAuth<Services, Session>
-  name?: string
-  description?: string
-}
-
-export const pikkuAuth = <
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
->(
-  auth:
-    | CorePikkuAuth<Services, Session>
-    | CorePikkuAuthConfig<Services, Session>
-): CorePikkuPermission<any, Services, any> => {
-  const fn = typeof auth === 'function' ? auth : auth.func
-  const wrapper = async (services: Services, _data: any, wire: any) => {
-    const session = wire.session
-    if (!session) return false
-    return fn(services, session as Session)
-  }
-  return wrapper as any
-}
-
-export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
-  | Record<string, PikkuPermission | PikkuPermission[]>
-  | undefined
-
-export type CorePikkuFunctionConfig<
-  PikkuFunction extends
-    | CorePikkuFunction<any, any, any, any, any>
-    | CorePikkuFunctionSessionless<any, any, any, any, any>,
-  PikkuPermission extends CorePikkuPermission<
-    any,
-    any,
-    any
-  > = CorePikkuPermission<any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
-    any,
-    any
-  >,
-  InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
-> = {
-  /** Optional human-readable title for the function */
-  title?: string
-  /** Optional description of what the function does */
-  description?: string
-  override?: string
-  version?: number
-  tags?: string[]
-  expose?: boolean
-  remote?: boolean
-  mcp?: boolean
-  readonly?: boolean
-  requiresApproval?: boolean
-  func: PikkuFunction
-  auth?: boolean
-  permissions?: CorePermissionGroup<PikkuPermission>
-  middleware?: PikkuMiddleware[]
-  input?: InputSchema
-  output?: OutputSchema
-  node?: CoreNodeConfig
-}

package/src/function/index.ts

@@ -1,5 +0,0 @@
-export { addFunction, getAllFunctionNames } from './function-runner.js'
-export type {
-  CorePikkuFunction,
-  CorePikkuFunctionSessionless,
-} from './functions.types.js'