@opensaas/stack-core 0.38.0 → 0.39.0

package/src/config/index.ts

@@ -8,16 +8,11 @@ import type {
 import { executePlugins } from './plugin-engine.js'
 import type { AccessControl } from '../access/types.js'
 
-/**
- * Normalize access control shorthand to object form
- * Converts function shorthand to { operation: { query, create, update, delete } } form
- */
 function normalizeListAccess<T>(
   access: ListAccessControl<T> | undefined,
 ): { operation?: OperationAccess<T> } | undefined {
   if (!access) return undefined
 
-  // If it's a function, convert to object form applying to all operations
   if (typeof access === 'function') {
     const fn = access as AccessControl<T>
     return {
@@ -30,32 +25,31 @@ function normalizeListAccess<T>(
     }
   }
 
-  // Already in object form
   return access
 }
 
 /**
- * Helper function to define configuration with type safety
- * Executes plugins if present in config.plugins array
+ * Define an OpenSaas config, executing `plugins` if present.
  *
- * Note: This function is now async when plugins are present
- * For synchronous config definition without plugins, config can still be returned directly
+ * Returns synchronously when there are no plugins (backward compatible);
+ * returns a `Promise` when plugins are present, since plugin execution is
+ * async.
  */
 export function config(userConfig: OpenSaasConfig): OpenSaasConfig | Promise<OpenSaasConfig> {
-  // If no plugins, return config as-is (synchronous, backward compatible)
   if (!userConfig.plugins || userConfig.plugins.length === 0) {
     return userConfig
   }
 
-  // Execute plugins and return promise
   return executePlugins(userConfig)
 }
 
 /**
- * Helper function to define a list with type safety
+ * Define a list with type safety.
  *
- * Accepts raw field configs and transforms them to inject the item type
- * This enables proper typing in field hooks where item is typed correctly
+ * `ListConfigInput<TTypeInfo>` accepts raw field configs; the return type
+ * `ListConfig<TTypeInfo>` injects `TTypeInfo` so hook/field callbacks (e.g.
+ * `resolveInput`'s `item`) are properly typed once `TTypeInfo` is supplied
+ * from generated types.
  *
  * @example
  * ```typescript
@@ -108,18 +102,15 @@ export function config(userConfig: OpenSaasConfig): OpenSaasConfig | Promise<Ope
 export function list<TTypeInfo extends import('./types.js').TypeInfo>(
   config: ListConfigInput<TTypeInfo>,
 ): ListConfig<TTypeInfo> {
-  // Normalize access control shorthand to object form
   const normalizedConfig = {
     ...config,
     access: normalizeListAccess(config.access),
   }
 
-  // At runtime, field configs are unchanged
-  // At type level, they're transformed to inject TypeInfo types
+  // Runtime shape is unchanged; the cast only narrows the TS type to inject TTypeInfo.
   return normalizedConfig as ListConfig<TTypeInfo>
 }
 
-// Re-export all types
 export type {
   OpenSaasConfig,
   OutputConfig,
@@ -171,16 +162,13 @@ export type {
   FileMetadata,
   ImageMetadata,
   ImageTransformationResult,
-  // Plugin system types
   Plugin,
   PluginContext,
   GeneratedFiles,
-  // List-level hook argument types
   ResolveInputHookArgs,
   ValidateHookArgs,
   BeforeOperationHookArgs,
   AfterOperationHookArgs,
-  // Field-level hook argument types
   FieldResolveInputHookArgs,
   FieldValidateHookArgs,
   FieldBeforeOperationHookArgs,

package/src/config/label.ts

@@ -1,16 +1,11 @@
 import type { ListConfig } from './types.js'
 
 /**
- * Resolve the field name that represents a list's rows as a single label —
- * the projection half of the label seam. `getItemLabel` reads exactly the
- * field this returns, so the field chosen for projection can never drift
- * from the field used for rendering.
+ * Resolve the field name used as a list's Label field: `ui.labelField` if
+ * set, else `name`, else `title`, else `id`.
  *
- * Fallback order: configured `ui.labelField` → `name` → `title` → `id`
- * (first field that exists on the list).
- *
- * @throws if `ui.labelField` is set but does not reference a declared,
- * non-relationship field on the list.
+ * @throws if `ui.labelField` names a field not declared on the list, or a
+ * relationship field (the Label field must be a scalar).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 export function getLabelFieldName(listConfig: ListConfig<any>): string {
@@ -37,10 +32,8 @@ export function getLabelFieldName(listConfig: ListConfig<any>): string {
 }
 
 /**
- * Resolve the display label for a single row — the render half of the label
- * seam. Reads the field `getLabelFieldName` resolves, falling back to `id`
- * when that field is missing from the row (e.g. stripped by field-level
- * access).
+ * Render a row's Label field ({@link getLabelFieldName}) as text, falling
+ * back to `item.id` when the value is `null`/`undefined`.
  */
 export function getItemLabel(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo

package/src/config/nav-count.ts

@@ -13,13 +13,12 @@ type CountDelegate = {
 
 /**
  * Whether a list's query access is **statically denied** — provably no session
- * can read any row without evaluating a session-dependent function.
+ * can read any row, without evaluating a session-dependent function.
  *
- * Mirrors the list view's `canDeleteList` static check (issue #733): query
- * access is statically denied when it is absent (deny-by-default, matching the
- * access engine) or the literal boolean `false`. A function — or `true` —
- * cannot be decided up front, so the count is fetched through the secured
- * context, which re-applies the real rule per row.
+ * Mirrors the list view's `canDeleteList` static check (issue #733): absent
+ * access is deny-by-default (matching the access engine), so only an explicit
+ * `false` counts as statically denied here — a function or `true` falls
+ * through to a real per-row check via the secured context.
  *
  * A statically-denied list must render no nav count at all: a `0` there would
  * imply "this list is empty" when the truth is "you may see none of it".
@@ -35,20 +34,13 @@ export function isListQueryStaticallyDenied(
 }
 
 /**
- * Resolve the access-scoped nav counts for the lists that opt in via
- * `ui.navCount` (issue #735).
+ * Resolve the access-scoped nav counts for lists that opt in via
+ * `ui.navCount` (issue #735). A list gets an entry only if it opts in, isn't
+ * a singleton (no meaningful count), and isn't {@link isListQueryStaticallyDenied}
+ * — everything else is omitted from the map, never zeroed.
  *
- * The returned map is keyed by list key and contains an entry **only** for a
- * list that:
- *
- * 1. opts in (`ui.navCount === true`) — no count query runs for any other list,
- * 2. is not a singleton (a single-record list has no meaningful count), and
- * 3. does not have statically-denied query access (see
- *    {@link isListQueryStaticallyDenied}).
- *
- * Each count is read through the secured `context.db`, whose `count` applies the
- * access filter, so the number reflects exactly what the current session may
- * see (a denied row is not counted). Counts are fetched concurrently.
+ * Each count is read through the secured `context.db`, so it reflects
+ * exactly what the current session may see.
  */
 export async function resolveNavCounts(
   context: AccessContext,

package/src/config/plugin-engine.ts

@@ -8,17 +8,12 @@ import type {
   BaseFieldConfig,
 } from './types.js'
 
-/**
- * Topological sort for plugin dependency resolution
- * Ensures plugins execute in correct order based on dependencies
- */
 function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
   const pluginMap = new Map<string, Plugin>()
   const visited = new Set<string>()
   const visiting = new Set<string>()
   const sorted: Plugin[] = []
 
-  // Build plugin map
   for (const plugin of plugins) {
     if (pluginMap.has(plugin.name)) {
       throw new Error(`Duplicate plugin name: ${plugin.name}`)
@@ -42,7 +37,6 @@ function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
 
     visiting.add(pluginName)
 
-    // Visit dependencies first
     if (plugin.dependencies) {
       for (const dep of plugin.dependencies) {
         visit(dep, [...path, pluginName])
@@ -54,7 +48,6 @@ function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
     sorted.push(plugin)
   }
 
-  // Visit all plugins
   for (const plugin of plugins) {
     visit(plugin.name)
   }
@@ -62,17 +55,12 @@ function sortPluginsByDependencies(plugins: Plugin[]): Plugin[] {
   return sorted
 }
 
-/**
- * Merge hooks from extension into existing hooks
- * Combines hook arrays so multiple plugins can add hooks
- */
 function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined): Hooks | undefined {
   if (!extension) return existing
   if (!existing) return extension
 
   const merged: Partial<Hooks> = {}
 
-  // Merge resolveInput hooks (chain them, passing resolvedData through)
   if (existing.resolveInput || extension.resolveInput) {
     if (existing.resolveInput && extension.resolveInput) {
       merged.resolveInput = async (args) => {
@@ -85,7 +73,6 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
     }
   }
 
-  // Merge validateInput hooks (run both)
   if (existing.validateInput || extension.validateInput) {
     if (existing.validateInput && extension.validateInput) {
       merged.validateInput = async (args) => {
@@ -97,7 +84,6 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
     }
   }
 
-  // Merge beforeOperation hooks (run both in sequence)
   if (existing.beforeOperation || extension.beforeOperation) {
     if (existing.beforeOperation && extension.beforeOperation) {
       merged.beforeOperation = async (args) => {
@@ -109,7 +95,6 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
     }
   }
 
-  // Merge afterOperation hooks (run both in sequence)
   if (existing.afterOperation || extension.afterOperation) {
     if (existing.afterOperation && extension.afterOperation) {
       merged.afterOperation = async (args) => {
@@ -124,33 +109,24 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
   return Object.keys(merged).length > 0 ? (merged as Hooks) : undefined
 }
 
-/**
- * Execute plugins and transform config
- * Returns modified config with plugin data attached
- */
 export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasConfig> {
   if (!config.plugins || config.plugins.length === 0) {
     return config
   }
 
-  // Sort plugins by dependencies
   const sortedPlugins = sortPluginsByDependencies(config.plugins)
 
-  // Initialize mutable config state - preserve all config properties
   let currentConfig: OpenSaasConfig = {
     ...config,
     lists: { ...config.lists }, // Clone lists object to avoid mutating original
     _pluginData: {},
   }
 
-  // Field type registry (for third-party fields)
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Registry must accept any field config builder
   const fieldTypeRegistry = new Map<string, (options?: unknown) => BaseFieldConfig<any>>()
 
-  // MCP tools registry
   const mcpToolsRegistry: McpCustomTool[] = []
 
-  // Execute each plugin
   for (const plugin of sortedPlugins) {
     const context: PluginContext = {
       config: currentConfig,
@@ -186,16 +162,13 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
           )
         }
 
-        // Deep merge fields
         const mergedFields = {
           ...existing.fields,
           ...extension.fields,
         }
 
-        // Merge hooks
         const mergedHooks = mergeHooks(existing.hooks, extension.hooks)
 
-        // Merge MCP config
         const mergedMcp = extension.mcp
           ? {
               ...existing.mcp,
@@ -233,11 +206,9 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
       },
     }
 
-    // Execute plugin init
     await plugin.init(context)
   }
 
-  // Store registered MCP tools in config (if any)
   if (mcpToolsRegistry.length > 0) {
     if (!currentConfig._pluginData) {
       currentConfig._pluginData = {}
@@ -245,8 +216,7 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
     currentConfig._pluginData.__mcpTools = mcpToolsRegistry
   }
 
-  // Store plugin instances in config for runtime access
-  // This allows context creation to call plugin.runtime() functions
+  // Stored so context creation can call each plugin's runtime() function.
   if (!currentConfig._plugins) {
     currentConfig._plugins = []
   }
@@ -255,9 +225,6 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
   return currentConfig
 }
 
-/**
- * Execute beforeGenerate hooks from plugins
- */
 export async function executeBeforeGenerateHooks(config: OpenSaasConfig): Promise<OpenSaasConfig> {
   if (!config.plugins || config.plugins.length === 0) {
     return config
@@ -274,9 +241,6 @@ export async function executeBeforeGenerateHooks(config: OpenSaasConfig): Promis
   return currentConfig
 }
 
-/**
- * Execute afterGenerate hooks from plugins
- */
 export async function executeAfterGenerateHooks(
   config: OpenSaasConfig,
   files: { prismaSchema: string; types: string; context: string; [key: string]: string },