@rizom/brain 0.2.0-alpha.234 → 0.2.0-alpha.236

package/dist/chunks/{index-srk70x0g.js.map → index-kga4gmhq.js.map}

@@ -5,6 +5,6 @@
     "import type {\n  DataSource,\n  DataSourceSchema,\n  BaseDataSourceContext,\n  IEntityService,\n  BaseEntity,\n  ListOptions,\n  SortField,\n  PaginationInfo,\n} from \"@brains/entity-service\";\nimport { buildPaginationInfo } from \"@brains/entity-service\";\nimport type { Logger } from \"@brains/utils/logger\";\nimport { z } from \"@brains/utils/zod\";\n\nexport type { SortField };\n\ninterface BaseQuerySchemaShape {\n  id: z.ZodOptional<z.ZodString>;\n  limit: z.ZodOptional<z.ZodNumber>;\n  page: z.ZodOptional<z.ZodNumber>;\n  pageSize: z.ZodOptional<z.ZodNumber>;\n  baseUrl: z.ZodOptional<z.ZodString>;\n}\n\ntype BaseQuerySchema = ReturnType<typeof z.looseObject<BaseQuerySchemaShape>>;\n\n/**\n * Zod schema for the base query fields.\n * Subclasses can extend this with `.extend()` for additional fields.\n */\nexport const baseQuerySchema: BaseQuerySchema = z.looseObject({\n  id: z.string().optional(),\n  limit: z.number().optional(),\n  page: z.number().optional(),\n  pageSize: z.number().optional(),\n  baseUrl: z.string().optional(),\n});\n\n/**\n * Zod schema for the outer datasource input (entityType + query).\n * Subclasses can extend the inner query via `baseQuerySchema.extend()`.\n */\ninterface BaseInputSchemaShape {\n  entityType: z.ZodOptional<z.ZodString>;\n  query: z.ZodOptional<typeof baseQuerySchema>;\n}\n\ntype BaseInputSchema = ReturnType<typeof z.looseObject<BaseInputSchemaShape>>;\n\nexport const baseInputSchema: BaseInputSchema = z.looseObject({\n  entityType: z.string().optional(),\n  query: baseQuerySchema.optional(),\n});\n\n/**\n * Parsed base query parameters.\n * Subclasses can extend this with additional fields via `parseQuery()`.\n */\nexport type BaseQuery = z.output<typeof baseQuerySchema>;\n\n/**\n * Navigation context for detail views (prev/next entities).\n */\nexport interface NavigationResult<T> {\n  prev: T | null;\n  next: T | null;\n}\n\n/**\n * Configuration for a BaseEntityDataSource.\n */\nexport interface EntityDataSourceConfig {\n  /** Entity type to query (e.g., \"post\", \"deck\", \"project\") */\n  entityType: string;\n  /** Default sort order for list and navigation queries */\n  defaultSort: SortField[];\n  /** Default limit for list queries (defaults to 100) */\n  defaultLimit?: number;\n  /**\n   * How to look up a single entity by the `id` query param.\n   * - \"slug\": filter by `metadata.slug` (default)\n   * - \"id\": direct `getEntity()` lookup\n   */\n  lookupField?: \"slug\" | \"id\";\n  /** Enable prev/next navigation on detail views (defaults to false) */\n  enableNavigation?: boolean;\n  /** Max entities to fetch when resolving prev/next navigation (defaults to 1000) */\n  navigationLimit?: number;\n}\n\n/**\n * Base class for entity datasources that follow the list/detail pattern.\n *\n * Provides:\n * - Query parsing with Zod validation\n * - Detail view: entity lookup (by slug or id), optional prev/next navigation\n * - List view: paginated fetch with sorting\n *\n * Subclasses implement:\n * - `transformEntity()` — convert raw entity to display format\n * - `buildListResult()` — shape the list response\n *\n * Optionally override:\n * - `buildDetailResult()` — shape the detail response (default throws; override\n *   this OR override `fetch()` to handle detail views directly)\n *\n * For datasources with extra query cases (e.g., \"latest\", \"series\", \"nextInQueue\"),\n * override `fetch()` to handle those first, then call `super.fetch()` for the standard path.\n */\nexport abstract class BaseEntityDataSource<\n  TEntity extends BaseEntity = BaseEntity,\n  TTransformed = TEntity,\n> implements DataSource {\n  protected readonly logger: Logger;\n  abstract readonly id: string;\n  abstract readonly name: string;\n  abstract readonly description: string;\n\n  protected abstract readonly config: EntityDataSourceConfig;\n\n  constructor(logger: Logger) {\n    this.logger = logger;\n  }\n\n  /**\n   * Transform a raw entity into the display format used by templates.\n   * Called for both list items and detail views.\n   */\n  protected abstract transformEntity(entity: TEntity): TTransformed;\n\n  /**\n   * Build the detail response object.\n   * Override this if using the base class's standard detail path.\n   * Datasources that fully override `fetch()` for detail views need not implement this.\n   *\n   * @param item - The transformed entity\n   * @param navigation - Prev/next entities (null if navigation is disabled)\n   */\n  protected buildDetailResult(\n    _item: TTransformed,\n    _navigation: NavigationResult<TTransformed> | null,\n  ): unknown {\n    throw new Error(\n      `${this.id}: buildDetailResult() not implemented. ` +\n        `Override this method or override fetch() to handle detail views.`,\n    );\n  }\n\n  /**\n   * Build the list response object.\n   * @param items - Transformed entities\n   * @param pagination - Pagination info (null if no page param was provided)\n   * @param query - The parsed query params (for passing through baseUrl, etc.)\n   */\n  protected abstract buildListResult(\n    items: TTransformed[],\n    pagination: PaginationInfo | null,\n    query: BaseQuery,\n  ): unknown;\n\n  /**\n   * Parse and validate the incoming query with Zod.\n   * Override to support additional query parameters beyond the base set.\n   * Use `baseQuerySchema.extend()` or `baseInputSchema` for validation.\n   */\n  protected parseQuery(query: unknown): {\n    entityType: string;\n    query: BaseQuery;\n  } {\n    const parsed = baseInputSchema.parse(query);\n    return {\n      entityType: parsed.entityType ?? this.config.entityType,\n      query: parsed.query ?? {},\n    };\n  }\n\n  /**\n   * Standard fetch implementation: dispatch to detail or list based on query.id.\n   *\n   * Override to handle custom query cases before falling through to the standard path:\n   * ```typescript\n   * async fetch<T>(query, outputSchema, context) {\n   *   const params = this.parseQuery(query);\n   *   if (params.query.latest) {\n   *     return this.fetchLatest(outputSchema, context.entityService);\n   *   }\n   *   return super.fetch(query, outputSchema, context);\n   * }\n   * ```\n   */\n  async fetch<T>(\n    query: unknown,\n    outputSchema: DataSourceSchema<T>,\n    context: BaseDataSourceContext,\n  ): Promise<T> {\n    const params = this.parseQuery(query);\n    const entityService = context.entityService;\n\n    if (params.query.id) {\n      const result = await this.fetchDetail(params.query.id, entityService);\n      return outputSchema.parse(\n        this.buildDetailResult(result.item, result.navigation),\n      );\n    }\n\n    const result = await this.fetchList(params.query, entityService);\n    return outputSchema.parse(\n      this.buildListResult(result.items, result.pagination, params.query),\n    );\n  }\n\n  // ── Protected utilities (available to subclasses for custom cases) ──\n\n  /**\n   * Fetch a single entity and optionally resolve prev/next navigation.\n   */\n  protected async fetchDetail(\n    id: string,\n    entityService: IEntityService,\n  ): Promise<{\n    item: TTransformed;\n    navigation: NavigationResult<TTransformed> | null;\n  }> {\n    const entity = await this.lookupEntity(id, entityService);\n    const item = this.transformEntity(entity);\n\n    let navigation: NavigationResult<TTransformed> | null = null;\n    if (this.config.enableNavigation) {\n      navigation = await this.resolveNavigation(entity, entityService);\n    }\n\n    return { item, navigation };\n  }\n\n  /**\n   * Fetch a paginated list of entities.\n   */\n  protected async fetchList(\n    query: BaseQuery,\n    entityService: IEntityService,\n    listOptions?: Partial<ListOptions>,\n  ): Promise<{ items: TTransformed[]; pagination: PaginationInfo | null }> {\n    const currentPage = query.page ?? 1;\n    const itemsPerPage =\n      query.pageSize ?? query.limit ?? this.config.defaultLimit ?? 100;\n    const offset = (currentPage - 1) * itemsPerPage;\n\n    const needsPagination = query.page !== undefined;\n\n    // Run list and count queries in parallel when pagination is needed\n    const [entities, totalItems] = await Promise.all([\n      entityService.listEntities<TEntity>({\n        entityType: this.config.entityType,\n        options: {\n          limit: itemsPerPage,\n          offset,\n          sortFields: this.config.defaultSort,\n          ...listOptions,\n        },\n      }),\n      needsPagination\n        ? entityService.countEntities({\n            entityType: this.config.entityType,\n            options: listOptions?.filter\n              ? { filter: listOptions.filter }\n              : undefined,\n          })\n        : Promise.resolve(0),\n    ]);\n\n    const items = entities.map((e) => this.transformEntity(e));\n\n    const pagination = needsPagination\n      ? buildPaginationInfo(totalItems, currentPage, itemsPerPage)\n      : null;\n\n    return { items, pagination };\n  }\n\n  /**\n   * Resolve prev/next navigation for a given entity within the sorted list.\n   */\n  protected async resolveNavigation(\n    entity: TEntity,\n    entityService: IEntityService,\n    sortFields?: SortField[],\n  ): Promise<NavigationResult<TTransformed>> {\n    const limit = this.config.navigationLimit ?? 1000;\n    const allEntities = await entityService.listEntities<TEntity>({\n      entityType: this.config.entityType,\n      options: {\n        limit,\n        sortFields: sortFields ?? this.config.defaultSort,\n      },\n    });\n\n    const currentIndex = allEntities.findIndex((e) => e.id === entity.id);\n    const prevEntity =\n      currentIndex > 0 ? allEntities[currentIndex - 1] : undefined;\n    const nextEntity =\n      currentIndex < allEntities.length - 1\n        ? allEntities[currentIndex + 1]\n        : undefined;\n    const prev = prevEntity ? this.transformEntity(prevEntity) : null;\n    const next = nextEntity ? this.transformEntity(nextEntity) : null;\n\n    return { prev, next };\n  }\n\n  /**\n   * Look up a single entity by id or slug.\n   * Uses `config.lookupField` to determine the strategy.\n   */\n  protected async lookupEntity(\n    id: string,\n    entityService: IEntityService,\n  ): Promise<TEntity> {\n    if (this.config.lookupField === \"id\") {\n      const entity = await entityService.getEntity<TEntity>({\n        entityType: this.config.entityType,\n        id: id,\n      });\n      if (!entity) {\n        throw new Error(`${this.config.entityType} not found: ${id}`);\n      }\n      return entity;\n    }\n\n    // Default: lookup by slug in metadata\n    const entities = await entityService.listEntities<TEntity>({\n      entityType: this.config.entityType,\n      options: {\n        filter: { metadata: { slug: id } },\n        limit: 1,\n      },\n    });\n\n    const entity = entities[0];\n    if (!entity) {\n      throw new Error(`${this.config.entityType} not found with slug: ${id}`);\n    }\n    return entity;\n  }\n}\n"
   ],
   "mappings": ";wFA8BO,FAAM,EAAmC,EAAE,YAAY,CAC5D,GAAI,EAAE,OAAO,EAAE,SAAS,EACxB,MAAO,EAAE,OAAO,EAAE,SAAS,EAC3B,KAAM,EAAE,OAAO,EAAE,SAAS,EAC1B,SAAU,EAAE,OAAO,EAAE,SAAS,EAC9B,QAAS,EAAE,OAAO,EAAE,SAAS,CAC/B,CAAC,EAaY,EAAmC,EAAE,YAAY,CAC5D,WAAY,EAAE,OAAO,EAAE,SAAS,EAChC,MAAO,EAAgB,SAAS,CAClC,CAAC,EAyDM,MAAe,CAGE,CACH,OAOnB,WAAW,CAAC,EAAgB,CAC1B,KAAK,OAAS,EAiBN,iBAAiB,CACzB,EACA,EACS,CACT,MAAU,MACR,GAAG,KAAK,2GAEV,EAoBQ,UAAU,CAAC,EAGnB,CACA,IAAM,EAAS,EAAgB,MAAM,CAAK,EAC1C,MAAO,CACL,WAAY,EAAO,YAAc,KAAK,OAAO,WAC7C,MAAO,EAAO,OAAS,CAAC,CAC1B,OAiBI,MAAQ,CACZ,EACA,EACA,EACY,CACZ,IAAM,EAAS,KAAK,WAAW,CAAK,EAC9B,EAAgB,EAAQ,cAE9B,GAAI,EAAO,MAAM,GAAI,CACnB,IAAM,EAAS,MAAM,KAAK,YAAY,EAAO,MAAM,GAAI,CAAa,EACpE,OAAO,EAAa,MAClB,KAAK,kBAAkB,EAAO,KAAM,EAAO,UAAU,CACvD,EAGF,IAAM,EAAS,MAAM,KAAK,UAAU,EAAO,MAAO,CAAa,EAC/D,OAAO,EAAa,MAClB,KAAK,gBAAgB,EAAO,MAAO,EAAO,WAAY,EAAO,KAAK,CACpE,OAQc,YAAW,CACzB,EACA,EAIC,CACD,IAAM,EAAS,MAAM,KAAK,aAAa,EAAI,CAAa,EAClD,EAAO,KAAK,gBAAgB,CAAM,EAEpC,EAAoD,KACxD,GAAI,KAAK,OAAO,iBACd,EAAa,MAAM,KAAK,kBAAkB,EAAQ,CAAa,EAGjE,MAAO,CAAE,OAAM,YAAW,OAMZ,UAAS,CACvB,EACA,EACA,EACuE,CACvE,IAAM,EAAc,EAAM,MAAQ,EAC5B,EACJ,EAAM,UAAY,EAAM,OAAS,KAAK,OAAO,cAAgB,IACzD,GAAU,EAAc,GAAK,EAE7B,EAAkB,EAAM,OAAS,QAGhC,EAAU,GAAc,MAAM,QAAQ,IAAI,CAC/C,EAAc,aAAsB,CAClC,WAAY,KAAK,OAAO,WACxB,QAAS,CACP,MAAO,EACP,SACA,WAAY,KAAK,OAAO,eACrB,CACL,CACF,CAAC,EACD,EACI,EAAc,cAAc,CAC1B,WAAY,KAAK,OAAO,WACxB,QAAS,GAAa,OAClB,CAAE,OAAQ,EAAY,MAAO,EAC7B,MACN,CAAC,EACD,QAAQ,QAAQ,CAAC,CACvB,CAAC,EAEK,EAAQ,EAAS,IAAI,CAAC,IAAM,KAAK,gBAAgB,CAAC,CAAC,EAEnD,EAAa,EACf,EAAoB,EAAY,EAAa,CAAY,EACzD,KAEJ,MAAO,CAAE,QAAO,YAAW,OAMb,kBAAiB,CAC/B,EACA,EACA,EACyC,CACzC,IAAM,EAAQ,KAAK,OAAO,iBAAmB,KACvC,EAAc,MAAM,EAAc,aAAsB,CAC5D,WAAY,KAAK,OAAO,WACxB,QAAS,CACP,QACA,WAAY,GAAc,KAAK,OAAO,WACxC,CACF,CAAC,EAEK,EAAe,EAAY,UAAU,CAAC,IAAM,EAAE,KAAO,EAAO,EAAE,EAC9D,EACJ,EAAe,EAAI,EAAY,EAAe,GAAK,OAC/C,EACJ,EAAe,EAAY,OAAS,EAChC,EAAY,EAAe,GAC3B,OACA,EAAO,EAAa,KAAK,gBAAgB,CAAU,EAAI,KACvD,EAAO,EAAa,KAAK,gBAAgB,CAAU,EAAI,KAE7D,MAAO,CAAE,OAAM,MAAK,OAON,aAAY,CAC1B,EACA,EACkB,CAClB,GAAI,KAAK,OAAO,cAAgB,KAAM,CACpC,IAAM,EAAS,MAAM,EAAc,UAAmB,CACpD,WAAY,KAAK,OAAO,WACxB,GAAI,CACN,CAAC,EACD,GAAI,CAAC,EACH,MAAU,MAAM,GAAG,KAAK,OAAO,yBAAyB,GAAI,EAE9D,OAAO,EAYT,IAAM,GARW,MAAM,EAAc,aAAsB,CACzD,WAAY,KAAK,OAAO,WACxB,QAAS,CACP,OAAQ,CAAE,SAAU,CAAE,KAAM,CAAG,CAAE,EACjC,MAAO,CACT,CACF,CAAC,GAEuB,GACxB,GAAI,CAAC,EACH,MAAU,MAAM,GAAG,KAAK,OAAO,mCAAmC,GAAI,EAExE,OAAO,EAEX",
-  "debugId": "644A3905F5F196DB64756E2164756E21",
+  "debugId": "6DC9B119EE2FE4CA64756E2164756E21",
   "names": []
 }