@nixxie-cms/core 1.0.0

package/src/types/config/index.ts

@@ -0,0 +1,333 @@
+import type { Server } from 'node:http'
+import type { ListenOptions } from 'node:net'
+
+import type { ApolloServerOptions } from '@apollo/server'
+import type { Options as BodyParserOptions } from 'body-parser'
+import type { CorsOptions } from 'cors'
+import type express from 'express'
+import type { GraphQLSchema } from 'graphql'
+
+import type {
+  BaseNixxieTypeInfo,
+  DatabaseProvider,
+  NixxieAuditService,
+  NixxieCacheService,
+  NixxieContext,
+  NixxieEmailService,
+  NixxieHealthService,
+  NixxieJobsService,
+  NixxieRateLimitService,
+  NixxieWebhooksService,
+} from '..'
+import type { SessionStrategy } from '../session'
+import type { MaybePromise } from '../utils'
+import type { FieldAccessControl, ListAccessControl } from './access-control'
+import type { BaseFields } from './fields'
+import type { FieldHooks, ListHooks } from './hooks'
+import type {
+  IdFieldConfig,
+  ListConfig,
+  MaybeItemFunctionWithFilter,
+  MaybeSessionFunction,
+} from './lists'
+
+export type * from './access-control'
+export type * from './fields'
+export type * from './lists'
+
+// copy of the Prisma's LogLevel types from `src/runtime/getLogLevel.ts`, as we dont have them
+type PrismaLogLevel = 'info' | 'query' | 'warn' | 'error'
+type PrismaLogDefinition = {
+  level: PrismaLogLevel
+  emit: 'stdout' | 'event'
+}
+
+export type NixxieConfigPre<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInfo> = {
+  types?: {
+    path: string
+  }
+
+  db: {
+    provider: DatabaseProvider
+    url: string
+
+    shadowDatabaseUrl?: string
+    onConnect?: (args: NixxieContext<TypeInfo>) => Promise<void>
+    enableLogging?: boolean | Array<PrismaLogLevel | PrismaLogDefinition>
+    idField?: IdFieldConfig
+    prismaClientPath?: string
+    prismaSchemaPath?: string
+
+    extendPrismaSchema?: (schema: string) => string
+    extendPrismaClient?: (client: any) => any
+  }
+
+  graphql?: {
+    // The path of the GraphQL API endpoint. Default: '/api/graphql'.
+    path?: string
+    // The CORS configuration to use on the GraphQL API endpoint.
+    // Default: { origin: 'https://studio.apollographql.com', credentials: true }
+    cors?: CorsOptions
+    bodyParser?: BodyParserOptions
+    /**
+     * - `true` - Add `ApolloServerPluginLandingPageGraphQLPlayground` to the Apollo Server plugins
+     * - `false` - Add `ApolloServerPluginLandingPageDisabled` to the Apollo Server plugins
+     * - `'apollo'` - Do not add any plugins to the Apollo config, this will use [Apollo Sandbox](https://www.apollographql.com/docs/apollo-server/testing/build-run-queries/#apollo-sandbox)
+     * @default process.env.NODE_ENV !== 'production'
+     */
+    playground?: boolean | 'apollo'
+    /**
+     *  Additional options to pass into the ApolloServer constructor.
+     *  @see https://www.apollographql.com/docs/apollo-server/api/apollo-server/#constructor
+     */
+    apolloConfig?: Partial<ApolloServerOptions<NixxieContext<TypeInfo>>>
+    /**
+     * When an error is returned from the GraphQL API, Apollo can include a stacktrace
+     * indicating where the error occurred. When Nixxie is processing mutations, it
+     * will sometimes captures more than one error at a time, and then group these into
+     * a single error returned from the GraphQL API. Each of these errors will include
+     * a stacktrace.
+     *
+     * In general both categories of stacktrace are useful for debugging while developing,
+     * but should not be exposed in production, and this is the default behaviour of Nixxie.
+     *
+     * You can use the `debug` option to change this behaviour. A use case for this
+     * would be if you need to send the stacktraces to a log, but do not want to return them
+     * from the API. In this case you could set `debug: true` and use
+     * `apolloConfig.formatError` to log the stacktraces and then strip them out before
+     * returning the error.
+     *
+     * ```ts
+     * graphql: {
+     *   debug: true,
+     *   apolloConfig: {
+     *     formatError: err => {
+     *       console.error(err)
+     *       delete err.extensions?.errors
+     *       delete err.extensions?.exception?.errors
+     *       delete err.extensions?.exception?.stacktrace
+     *       return err
+     *     },
+     *   },
+     * }
+     * ```
+     *
+     * @default process.env.NODE_ENV !== 'production'
+     */
+    debug?: boolean
+
+    /**
+     * The path to GraphQL schema
+     * @default 'schema.graphql'
+     */
+    schemaPath?: string
+
+    /**
+     * A function that receives the Nixxie GraphQL schema for the developer to extend
+     * @default 'schema.graphql'
+     */
+    extendGraphqlSchema?: (schema: GraphQLSchema) => GraphQLSchema
+  }
+
+  lists: Record<string, ListConfig<any>>
+  server?: {
+    /** Configuration options for the cors middleware. Set to `true` to use Nixxie's defaults */
+    cors?: boolean | CorsOptions
+
+    /** Maximum upload file size allowed (in bytes) */
+    maxFileSize?: number
+
+    /** extend the Express application used by Nixxie */
+    extendExpressApp?: (
+      app: express.Express,
+      context: NixxieContext<TypeInfo>
+    ) => MaybePromise<void>
+
+    /** extend the node:http server used by Nixxie */
+    extendHttpServer?: (server: Server, context: NixxieContext<TypeInfo>) => MaybePromise<void>
+  } & (
+    | {
+        /** Port number to start the server on. Defaults to process.env.PORT || 3000 */
+        port?: number
+      }
+    | {
+        /** node http.Server options */
+        options?: ListenOptions
+      }
+  )
+
+  session?: SessionStrategy<TypeInfo['session'], TypeInfo>
+
+  /**
+   * Email service instance created with `createEmail()` from `@nixxie-cms/email`.
+   * Once configured, it is available everywhere as `context.services.email`.
+   *
+   * @example
+   * ```ts
+   * import { createEmail } from '@nixxie-cms/email'
+   * export default config({
+   *   email: createEmail({ transport: { type: 'resend', apiKey: process.env.RESEND_API_KEY! }, from: 'app@example.com' }),
+   * })
+   * ```
+   */
+  email?: NixxieEmailService
+
+  /**
+   * Background job scheduler created with `createJobs()` from `@nixxie-cms/jobs`.
+   * Available as `context.services.jobs`. Supports cron expressions and interval-based scheduling.
+   *
+   * @example
+   * ```ts
+   * import { createJobs } from '@nixxie-cms/jobs'
+   * export default config({
+   *   jobs: createJobs({
+   *     jobs: [{ name: 'cleanup', schedule: '0 3 * * *', handler: async () => { ... } }],
+   *   }),
+   * })
+   * ```
+   */
+  jobs?: NixxieJobsService
+
+  /**
+   * Cache service created with `createCache()` from `@nixxie-cms/cache`.
+   * Available as `context.services.cache`. Supports in-memory (LRU) and Redis backends.
+   *
+   * @example
+   * ```ts
+   * import { createCache } from '@nixxie-cms/cache'
+   * export default config({
+   *   cache: createCache({ store: 'memory', max: 500, ttl: 60_000 }),
+   * })
+   * ```
+   */
+  cache?: NixxieCacheService
+
+  /**
+   * Audit log service created with `createAudit()` from `@nixxie-cms/audit`.
+   * Available as `context.services.audit`. Records who did what and when.
+   *
+   * @example
+   * ```ts
+   * import { createAudit } from '@nixxie-cms/audit'
+   * export default config({
+   *   audit: createAudit({ store: 'memory', maxEntries: 10_000 }),
+   * })
+   * ```
+   */
+  audit?: NixxieAuditService
+
+  /**
+   * Outbound webhook service created with `createWebhooks()` from `@nixxie-cms/webhooks`.
+   * Available as `context.services.webhooks`. Manages subscriptions and reliable delivery with retry.
+   *
+   * @example
+   * ```ts
+   * import { createWebhooks } from '@nixxie-cms/webhooks'
+   * export default config({
+   *   webhooks: createWebhooks({ retries: 3, timeout: 10_000 }),
+   * })
+   * ```
+   */
+  webhooks?: NixxieWebhooksService
+
+  /**
+   * Rate limiting service created with `createRateLimit()` from `@nixxie-cms/rate-limit`.
+   * Available as `context.services.rateLimit`. Sliding-window counters backed by memory or Redis.
+   *
+   * @example
+   * ```ts
+   * import { createRateLimit } from '@nixxie-cms/rate-limit'
+   * export default config({
+   *   rateLimit: createRateLimit({ store: 'memory' }),
+   * })
+   * ```
+   */
+  rateLimit?: NixxieRateLimitService
+
+  /**
+   * Health-check service created with `createHealth()` from `@nixxie-cms/health`.
+   * Available as `context.services.health`. Auto-exposes `/health/live` and `/health/ready`
+   * when mounted via `extendExpressApp`.
+   *
+   * @example
+   * ```ts
+   * import { createHealth } from '@nixxie-cms/health'
+   * export default config({
+   *   health: createHealth(),
+   *   server: {
+   *     extendExpressApp: async (app, context) => {
+   *       context.services.health.register('db', async () => {
+   *         await context.prisma.$queryRaw`SELECT 1`
+   *         return { ok: true }
+   *       })
+   *       app.use('/health', context.services.health.router())
+   *     },
+   *   },
+   * })
+   * ```
+   */
+  health?: NixxieHealthService
+
+  /** Telemetry boolean to disable telemetry for this project */
+  telemetry?: boolean
+
+  ui?: {
+    /** Completely disables the Admin UI */
+    isDisabled?: boolean
+
+    /** A function that can be run to validate that the current session should have access to the Admin UI */
+    isAccessAllowed?: (context: NixxieContext<TypeInfo>) => MaybePromise<boolean>
+
+    /** An array of page routes that bypass the isAccessAllowed function */
+    publicPages?: readonly string[]
+
+    /** The Base Path for Nixxies Admin UI */
+    basePath?: string
+
+    getAdditionalFiles?: () => MaybePromise<readonly AdminFileToWrite[]>
+
+    /** An async middleware function that can optionally return a redirect */
+    pageMiddleware?: (args: {
+      context: NixxieContext<TypeInfo>
+      wasAccessAllowed: boolean
+      basePath: string
+    }) => MaybePromise<{ kind: 'redirect'; to: string } | void>
+  }
+}
+
+export type NixxieConfig<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInfo> = {
+  types: NixxieConfigPre<TypeInfo>['types']
+  db: Omit<Required<NixxieConfigPre<TypeInfo>['db']>, 'enableLogging'> & {
+    enableLogging: PrismaLogLevel | Array<PrismaLogLevel | PrismaLogDefinition>
+  }
+  graphql: NonNullable<NixxieConfigPre<TypeInfo>['graphql']> & {
+    path: string
+  }
+  lists: {
+    [listKey: string]: {
+      listKey: string
+    } & Required<NixxieConfigPre<TypeInfo>['lists'][string]>
+  }
+  server: Omit<Required<NonNullable<NixxieConfigPre<TypeInfo>['server']>>, 'cors' | 'port'> & {
+    cors: CorsOptions | null
+    options: ListenOptions
+  }
+  session: NixxieConfigPre<TypeInfo>['session']
+  email: NixxieEmailService | undefined
+  jobs: NixxieJobsService | undefined
+  cache: NixxieCacheService | undefined
+  audit: NixxieAuditService | undefined
+  webhooks: NixxieWebhooksService | undefined
+  rateLimit: NixxieRateLimitService | undefined
+  health: NixxieHealthService | undefined
+  telemetry: boolean
+  ui: NonNullable<Required<NixxieConfigPre<TypeInfo>['ui']>>
+}
+
+export type { BaseFields, ListConfig, MaybeItemFunctionWithFilter, MaybeSessionFunction }
+
+export type AdminFileToWrite =
+  | { mode: 'write'; src: string; outputPath: string }
+  | { mode: 'copy'; inputPath: string; outputPath: string }
+
+export type { FieldAccessControl, FieldHooks, ListAccessControl, ListHooks }