deprecate collection function

.changeset/chilly-wombats-attend.md

@@ -0,0 +1,17 @@
+---
+'renoun': minor
+---
+
+Deprecates the `collection` utility in favor of using the `Collection` class directly:
+
+```diff
+-- import { collection } from 'renoun/collections'
+++ import { Collection } from 'renoun/collections'
+
+-- export const PostsCollection = collection({
+++ export const PostsCollection = new Collection({
+  filePattern: 'posts/*.mdx',
+  baseDirectory: 'posts',
+  basePath: 'posts',
+})
+```

.changeset/famous-hairs-vanish.md

@@ -2,20 +2,25 @@
 'renoun': minor
 ---
 
-Introduces a concept of "composite collections". This allows overloading the `collection` utility to treat a set of collections as a single collection:
+Introduces a new `CompositeCollection` class. This allows grouping a set of collections to treat them as a single collection:
 
 ```tsx
-const CollectionsCollection = collection({
+import { Collection, CompositeCollection } from 'renoun/collections'
+
+const CollectionsCollection = new Collection({
   filePattern: 'src/collections/index.tsx',
   baseDirectory: 'collections',
 })
 
-const ComponentsCollection = collection({
+const ComponentsCollection = new Collection({
   filePattern: 'src/components/**/*.{ts,tsx}',
   baseDirectory: 'components',
 })
 
-const AllCollections = collection(CollectionsCollection, ComponentsCollection)
+const AllCollections = new CompositeCollection(
+  CollectionsCollection,
+  ComponentsCollection
+)
 ```
 
 When getting a source from a composite collection, the `<FileSystemSource>.getSiblings` method will account for all collections in the composite collection:

apps/site/collections.ts

@@ -1,5 +1,6 @@
 import {
-  collection,
+  Collection,
+  CompositeCollection,
   isExportSource,
   isFileSystemSource,
   type FileSystemSource,
@@ -21,7 +22,7 @@ type DocsSchema = {
 
 export type DocsSource = FileSystemSource<DocsSchema>
 
-export const DocsCollection = collection<DocsSchema>(
+export const DocsCollection = new Collection<DocsSchema>(
   {
     filePattern: 'docs/**/*.mdx',
     baseDirectory: 'docs',
@@ -30,7 +31,7 @@ export const DocsCollection = collection<DocsSchema>(
   (slug) => import(`./docs/${slug}.mdx`)
 )
 
-export const GuidesCollection = collection<DocsSchema>(
+export const GuidesCollection = new Collection<DocsSchema>(
   {
     filePattern: 'guides/**/*.mdx',
     baseDirectory: 'guides',
@@ -69,7 +70,7 @@ type CollectionsSchema = Record<string, React.ComponentType>
 
 export type CollectionsSource = FileSystemSource<CollectionsSchema>
 
-export const CollectionsCollection = collection<CollectionsSchema>(
+export const CollectionsCollection = new Collection<CollectionsSchema>(
   {
     filePattern: 'src/collections/*.tsx',
     baseDirectory: 'collections',
@@ -91,7 +92,7 @@ type CollectionsDocsSchema = {
   headings: Headings
 }
 
-export const CollectionsDocsCollection = collection<CollectionsDocsSchema>(
+export const CollectionsDocsCollection = new Collection<CollectionsDocsSchema>(
   {
     filePattern: 'src/collections/docs/*.mdx',
     baseDirectory: 'src/collections/docs',
@@ -108,7 +109,7 @@ type ComponentSchema = Record<string, React.ComponentType>
 
 export type ComponentSource = FileSystemSource<ComponentSchema>
 
-export const ComponentsCollection = collection<ComponentSchema>(
+export const ComponentsCollection = new Collection<ComponentSchema>(
   {
     filePattern: 'src/components/**/*.{ts,tsx}',
     baseDirectory: 'components',
@@ -122,7 +123,7 @@ export const ComponentsCollection = collection<ComponentSchema>(
   ]
 )
 
-export const ComponentsMDXCollection = collection<{
+export const ComponentsMDXCollection = new Collection<{
   default: MDXContent
   headings: Headings
 }>(
@@ -135,7 +136,7 @@ export const ComponentsMDXCollection = collection<{
   (slug) => import(`../../packages/renoun/src/components/${slug}.mdx`)
 )
 
-export const AllCollections = collection(
+export const AllCollections = new CompositeCollection(
   DocsCollection,
   GuidesCollection,
   ComponentsCollection

packages/renoun/src/collections/docs/index.mdx

@@ -89,19 +89,22 @@ In addition to creating individual collections, renoun also allows you to define
 Let's say you have two collections, one for blog posts, and another for components. Using a composite collection, you can combine these into a single collection that can be queried as if it were one:
 
 ```tsx
-import { collection } from 'renoun/collections'
+import { Collection, CompositeCollection } from 'renoun/collections'
 
-const PostsCollection = collection({
+const PostsCollection = new Collection({
   filePattern: 'posts/*.mdx',
   baseDirectory: 'posts',
 })
 
-const ComponentsCollection = collection({
+const ComponentsCollection = new Collection({
   filePattern: 'src/components/**/*.{ts,tsx}',
   baseDirectory: 'components',
 })
 
-const AllCollections = collection(PostsCollection, ComponentsCollection)
+const AllCollections = new CompositeCollection(
+  PostsCollection,
+  ComponentsCollection
+)
 ```
 
 With this setup, `AllCollections` allows you to query across both `PostsCollection` and `ComponentsCollection` seamlessly.

packages/renoun/src/collections/index.test.ts

@@ -1,21 +1,21 @@
 import type { ComponentType } from 'react'
 import { describe, it, expect } from 'vitest'
 
-import { collection } from './index'
+import { Collection, CompositeCollection } from './index'
 
 describe('collections', () => {
   it('merges composite collection siblings', async () => {
-    const CollectionsCollection = collection({
+    const CollectionsCollection = new Collection({
       filePattern: 'src/collections/index.tsx',
       baseDirectory: 'collections',
     })
-    const ComponentsCollection = collection<{
+    const ComponentsCollection = new Collection<{
       [key: string]: ComponentType
     }>({
       filePattern: 'src/components/**/*.{ts,tsx}',
       baseDirectory: 'components',
     })
-    const AllCollections = collection(
+    const AllCollections = new CompositeCollection(
       CollectionsCollection,
       ComponentsCollection
     )

packages/renoun/src/collections/index.tsx

@@ -794,7 +794,7 @@ You can fix this error by taking one of the following actions:
 }
 
 /** Creates a collection of file system sources based on a file pattern. */
-class Collection<AllExports extends FileExports>
+export class Collection<AllExports extends FileExports>
   implements CollectionSource<AllExports>
 {
   public options: CollectionOptions<AllExports>
@@ -1123,7 +1123,7 @@ type FileSystemSourceUnion<Collections extends CollectionSource<any>[]> = {
  * Combines multiple collections into a single source provider that can be queried together.
  * This is useful for creating feeds or navigations that span multiple collections.
  */
-class CompositeCollection<Collections extends CollectionSource<any>[]>
+export class CompositeCollection<Collections extends CollectionSource<any>[]>
   implements SourceProvider<any>
 {
   private collections: Collections
@@ -1168,42 +1168,18 @@ class CompositeCollection<Collections extends CollectionSource<any>[]>
  * Creates a collection of file system sources based on a file pattern.
  * Note, a dynamic import getter will automatically be generated for each file extension at the call site of this collection.
  *
+ * @deprecated Use the `Collection` class directly.
  * @param options - Settings for the collection, including base directory, base path, TypeScript config file path, and a custom sort function.
  * @param getImport - A dynamic import getter function that returns the module exports for a given slug. This is automatically generated based on the `filePattern` extensions.
  * @returns A collection object that provides methods to retrieve all sources or an individual source that match the file pattern.
  */
-export function collection<AllExports extends FileExports = FileExports>(
+export function collection<
+  AllExports extends { [key: string]: any } = { [key: string]: any },
+>(
   options: CollectionOptions<AllExports>,
   getImport?: GetImport | GetImport[]
-): CollectionSource<AllExports>
-
-/**
- * Creates a composite collection of file system sources based on multiple collections.
- * This is useful for creating feeds or navigations that span multiple collections.
- *
- * @param collections - A list of collections to combine.
- * @returns A composite collection that provides methods to retrieve all sources or an individual source.
- */
-export function collection<Collections extends CollectionSource<any>[]>(
-  ...collections: Collections
-): CompositeCollection<Collections>
-
-export function collection<AllExports extends FileExports = FileExports>(
-  ...args:
-    | [CollectionOptions<AllExports>, (GetImport | GetImport[])?]
-    | CollectionSource<AllExports>[]
-):
-  | CollectionSource<AllExports>
-  | CompositeCollection<CollectionSource<AllExports>[]> {
-  if (args[0] instanceof Collection) {
-    return new CompositeCollection(...(args as CollectionSource<AllExports>[]))
-  } else {
-    const [options, getImport] = args as [
-      CollectionOptions<AllExports>,
-      GetImport?,
-    ]
-    return new Collection<AllExports>(options, getImport)
-  }
+): CollectionSource<AllExports> {
+  return new Collection<AllExports>(options, getImport)
 }
 
 /** Get all sources for a file pattern. */