@coffic/cosy-ui 0.9.4 → 0.9.5

package/dist/src-astro/collection/repos/BaseRepo.ts

@@ -0,0 +1,276 @@
+import {
+    getCollection,
+    getEntry,
+    type CollectionEntry,
+} from 'astro:content';
+import { cosyLogger, ERROR_PREFIX } from '../../cosy';
+import type { BaseDoc } from '../entities/BaseDoc';
+
+/**
+ * BaseDB 是所有数据库类的基类，提供了通用的文档操作功能。
+ *
+ * 使用方法：
+ * ```typescript
+ * class MyDB extends BaseDB<'collection', MyEntry, MyDoc> {
+ *     protected collectionName = 'collection' as const;
+ *     protected createDoc(entry: MyEntry): MyDoc {
+ *         return new MyDoc(entry);
+ *     }
+ * }
+ *
+ * // 使用单例模式获取实例
+ * const db = MyDB.getInstance();
+ * const docs = await db.allTopLevelDocs();
+ * ```
+ *
+ * 类型参数说明：
+ * @template Collection - Astro content collection 的名称
+ * @template Entry - Collection 对应的条目类型
+ * @template Doc - 文档类型，通常是自定义的文档类
+ */
+export abstract class BaseDB<
+    Collection extends string,
+    Entry extends CollectionEntry<Collection>,
+    Doc extends BaseDoc,
+> {
+    /**
+     * 集合名称，必须在子类中指定
+     * 
+     * 例如：
+     * ```typescript
+     * protected collectionName = 'blogs' as const;
+     * ```
+     */
+    protected abstract collectionName: Collection;
+
+    /**
+     * 创建文档实例的方法，必须在子类中实现
+     * @param entry - 集合条目
+     * @returns 文档实例
+     */
+    protected abstract createDoc(entry: Entry): Doc;
+
+    /**
+     * 获取所有文档的ID
+     * @returns 返回所有文档的ID数组
+     */
+    protected async getAllIds(): Promise<string[]> {
+        const entries = await getCollection(this.collectionName);
+        return entries.map((entry: CollectionEntry<Collection>) => entry.id);
+    }
+
+    /**
+     * 获取集合中的所有条目
+     * @returns 返回所有条目的数组
+     */
+    protected async getEntries(): Promise<Entry[]> {
+        return await getCollection(this.collectionName);
+    }
+
+    /**
+     * 获取指定深度的文档
+     * 深度是指文档 ID 中斜杠的数量加1
+     * 例如：
+     * - "blog.md" 深度为1
+     * - "zh-cn/blog.md" 深度为2
+     * - "zh-cn/tech/blog.md" 深度为3
+     *
+     * @param depth - 文档深度
+     * @returns 返回指定深度的文档数组
+     */
+    protected async getDocsByDepth(depth: number): Promise<Doc[]> {
+        const entries = await getCollection(
+            this.collectionName,
+            ({ id }: { id: string }) => id.split('/').length === depth
+        );
+
+        if (entries.length === 0) {
+            cosyLogger.warn(
+                `[BaseDB] 没有找到深度为${depth}的文档(collection=${this.collectionName as string})`
+            );
+            const allEntries = await getCollection(this.collectionName);
+            cosyLogger.array(
+                '[BaseDB] 所有文档',
+                allEntries.map((entry: CollectionEntry<Collection>) => entry.id)
+            );
+            return [];
+        }
+
+        return entries.map((entry: CollectionEntry<Collection>) =>
+            this.createDoc(entry as Entry)
+        );
+    }
+
+    /**
+     * 根据ID查找单个文档
+     * @param id - 文档ID
+     * @param debug - 是否启用调试模式, 默认为false
+     * @throws 如果ID不是字符串类型，则抛出错误
+     * @throws 如果文档不存在，则返回null
+     * @throws 如果发生其他错误，则抛出错误
+     * @returns 返回找到的文档，如果不存在则返回null
+     */
+    async find(id: string, debug: boolean = false): Promise<Doc | null> {
+        if (debug) {
+            cosyLogger.info(`查找文档，ID: ${id}`);
+        }
+
+        if (id == undefined) {
+            cosyLogger.error('ID is undefined');
+            throw new Error(ERROR_PREFIX + 'ID is undefined');
+        }
+
+        if (typeof id !== 'string') {
+            cosyLogger.error('ID must be a string, but got ' + typeof id);
+            cosyLogger.debug(id);
+            throw new Error(
+                ERROR_PREFIX + 'ID must be a string, but got ' + typeof id
+            );
+        }
+
+        // 获取所有文档的ID并排好顺序
+        if (debug) {
+            const allIds = (await this.getAllIds()).sort();
+            cosyLogger.array('所有文档的ID', allIds);
+        }
+
+        // 根据ID查找文档
+        const entry = await getEntry(this.collectionName, id);
+        return entry ? this.createDoc(entry as Entry) : null;
+    }
+
+    /**
+     * 获取指定文档的直接子文档（不包括更深层级的文档）
+     * 例如对于文档 "zh-cn/blog"：
+     * - "zh-cn/blog/post1.md" 会被包含
+     * - "zh-cn/blog/2024/post2.md" 不会被包含
+     *
+     * @param parentId - 父文档ID
+     * @returns 返回子文档数组
+     */
+    async getChildren(parentId: string): Promise<Doc[]> {
+        const parentLevel = parentId.split('/').length;
+        const childrenLevel = parentLevel + 1;
+
+        const entries = await getCollection(
+            this.collectionName,
+            ({ id }: { id: string }) =>
+                id.startsWith(parentId) && id.split('/').length === childrenLevel
+        );
+
+        return entries.map((entry: CollectionEntry<Collection>) =>
+            this.createDoc(entry as Entry)
+        );
+    }
+
+    /**
+     * 获取指定文档的所有后代文档（包括所有层级）
+     * 例如对于文档 "zh-cn/blog"，以下都会被包含：
+     * - "zh-cn/blog/post1.md"
+     * - "zh-cn/blog/2024/post2.md"
+     * - "zh-cn/blog/2024/tech/post3.md"
+     *
+     * @param parentId - 父文档ID
+     * @returns 返回所有后代文档数组
+     */
+    async getDescendantDocs(parentId: string): Promise<Doc[]> {
+        const entries = await getCollection(
+            this.collectionName,
+            ({ id }: { id: string }) => id.startsWith(parentId)
+        );
+        return entries.map((entry: CollectionEntry<Collection>) =>
+            this.createDoc(entry as Entry)
+        );
+    }
+
+    /**
+     * 获取指定语言和级别的文档
+     * 通过检查文档ID是否以指定语言代码开头来筛选
+     *
+     * @param lang - 语言代码（如 'zh-cn', 'en'）
+     * @param level - 文档级别
+     * @returns 返回指定语言和级别的文档数组
+     */
+    protected async allDocsByLangAndLevel(
+        lang: string,
+        level: number = 1,
+        debug: boolean = false
+    ): Promise<Doc[]> {
+        const collectionName = this.collectionName as string;
+        const docs = await this.getDocsByDepth(level);
+
+        if (debug) {
+            cosyLogger.array(
+                `[BaseDB] 所有${level}级文档(lang=any,collection=${collectionName})`,
+                docs
+            );
+        }
+
+        if (docs.length === 0) {
+            cosyLogger.warn(
+                `[BaseDB] 没有找到${level}级文档(lang=any,collection=${collectionName})`
+            );
+            return [];
+        }
+
+        const filteredDocs = docs.filter((doc) => {
+            const id = (doc as any).getId();
+            return id && typeof id === 'string' && id.startsWith(lang);
+        });
+
+        if (debug) {
+            cosyLogger.array(
+                `[BaseDB] 所有${level}级文档(lang=${lang},collection=${collectionName})`,
+                filteredDocs
+            );
+        }
+
+        if (filteredDocs.length === 0) {
+            cosyLogger.warn(
+                `[BaseDB] 没有找到${level}级文档(lang=${lang},collection=${collectionName})`
+            );
+            cosyLogger.array(
+                `[BaseDB] 所有${level}级文档`,
+                docs.map((doc) => doc.getId())
+            );
+            return [];
+        }
+
+        return filteredDocs;
+    }
+
+    /**
+     * 获取用于 Astro 静态路由生成的路径参数
+     * 为每个文档生成包含语言和slug的路径参数
+     *
+     * @returns 返回路径参数数组，每个元素包含 lang 和 slug
+     * @example
+     * ```typescript
+     * const paths = await db.getStaticPaths();
+     * // 返回格式：
+     * // [
+     * //   { params: { lang: 'zh-cn', slug: 'post1' } },
+     * //   { params: { lang: 'en', slug: 'post1' } }
+     * // ]
+     * ```
+     */
+    async getStaticPaths() {
+        const debug = false;
+        const docs = await this.getDescendantDocs('');
+        const paths = docs.map((doc) => {
+            const docWithMethods = doc as any;
+            return {
+                params: {
+                    lang: docWithMethods.getLang?.() || '',
+                    slug: docWithMethods.getSlug?.() || '',
+                },
+            };
+        });
+
+        if (debug) {
+            cosyLogger.array('所有文档的路径', paths);
+        }
+
+        return paths;
+    }
+}

package/dist/src-astro/collection/repos/BlogRepo.ts

@@ -0,0 +1,226 @@
+import BlogDoc from '../entities/BlogDoc';
+import type Tag from '../entities/Tag';
+import { cosyLogger } from '../../cosy';
+import { defineCollection, z, type CollectionEntry } from 'astro:content';
+import { BaseDB } from './BaseRepo';
+import { glob } from 'astro/loaders';
+
+export const COLLECTION_BLOG = 'blogs' as const;
+export type BlogEntry = CollectionEntry<typeof COLLECTION_BLOG>;
+
+/**
+ * 博客数据库类，用于管理博客内容集合。
+ *
+ * 目录结构：
+ * ```
+ * blogs/
+ * ├── zh-cn/
+ * │   ├── typescript-intro.md      # 文章内容  
+ * │   ├── images/                  # 文章相关图片
+ * │   └── web-performance.md
+ * └── en/
+ *     └── typescript-intro.md
+ *     └── images/
+ *     └── web-performance.md
+ * ```
+ */
+class BlogRepo extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
+    protected collectionName = COLLECTION_BLOG;
+
+    protected createDoc(entry: BlogEntry): BlogDoc {
+        return BlogDoc.fromEntry(entry);
+    }
+
+    /**
+     * 获取所有博客
+     *
+     * @returns {Promise<BlogDoc[]>} 返回所有博客
+     */
+    async allBlogs(): Promise<BlogDoc[]> {
+        const debug = false;
+        const entries = await this.getDocsByDepth(2);
+
+        if (debug) {
+            cosyLogger.array('所有博客文档', entries);
+        }
+
+        return entries;
+    }
+
+    /**
+     * 获取指定语言的所有博客
+     *
+     * @param lang - 语言代码
+     * @returns {Promise<BlogDoc[]>} 返回指定语言的所有博客
+     */
+    async allBlogsByLang(lang: string): Promise<BlogDoc[]> {
+        const docs = await this.allBlogs();
+        const filteredEntries = docs.filter((doc) => doc.getId().startsWith(lang));
+
+        return filteredEntries;
+    }
+
+    /**
+     * 获取用于 Astro 静态路由生成的路径参数，专门配合 [lang]/blogs/[slug].astro 使用
+     *
+     * @param debug - 是否开启调试模式
+     * @returns 返回路径参数数组
+     */
+    async getStaticPaths(debug: boolean = false) {
+        const docs = await this.allBlogs();
+
+        const paths = docs.map((doc) => {
+            return {
+                params: {
+                    lang: doc.getLang(),
+                    slug: doc.getSlug(),
+                },
+            };
+        });
+
+        if (debug) {
+            cosyLogger.array('所有博客文档的路径', paths);
+        }
+
+        return paths;
+    }
+
+    /**
+     * 获取所有博客标签
+     * 标签会根据语言和名称去重，使用复合键 "lang:name" 确保唯一性
+     *
+     * @returns 返回所有标签数组
+     * 返回格式：
+     * [
+     *   { name: 'typescript', lang: 'zh-cn', count: 5 },
+     *   { name: 'javascript', lang: 'en', count: 3 }
+     * ]
+     */
+    async getTags(): Promise<Tag[]> {
+        const tagsMap = new Map<string, Tag>();
+        const posts = await this.allBlogs();
+
+        posts.forEach((post) => {
+            post.getTags().forEach((tag) => {
+                const key = `${tag.lang}:${tag.name}`;
+                if (!tagsMap.has(key)) {
+                    tagsMap.set(key, tag);
+                }
+            });
+        });
+
+        return Array.from(tagsMap.values());
+    }
+
+    /**
+     * 获取指定语言的博客标签
+     *
+     * @param lang - 语言代码（如 'zh-cn', 'en'）
+     * @returns 返回指定语言的标签数组
+     */
+    async getTagsByLang(lang: string): Promise<Tag[]> {
+        const debug = false;
+        const tagsMap = new Map<string, Tag>();
+        const posts = await this.allBlogsByLang(lang);
+
+        if (debug) {
+            cosyLogger.array('posts', posts);
+        }
+
+        if (posts.length === 0) {
+            return [];
+        }
+
+        posts.forEach((post) => {
+            post.getTags().forEach((tag) => {
+                const key = `${tag.lang}:${tag.name}`;
+                if (!tagsMap.has(key)) {
+                    tagsMap.set(key, tag);
+                }
+            });
+        });
+
+        if (debug) {
+            cosyLogger.array('tags', Array.from(tagsMap.values()));
+        }
+
+        return Array.from(tagsMap.values());
+    }
+
+    /**
+     * 获取指定标签和语言的博客文章
+     *
+     * @param tag - 标签名称
+     * @param lang - 语言代码
+     * @returns 返回匹配的博客文档数组
+     * @example
+     * ```typescript
+     * const posts = await blogDB.getBlogsByTag('typescript', 'zh-cn');
+     * // 返回所有包含 'typescript' 标签的中文博客
+     * ```
+     */
+    async getBlogsByTag(tag: string, lang: string): Promise<BlogDoc[]> {
+        const posts = await this.allBlogsByLang(lang);
+        return posts.filter((post) => post.getTags().some((t) => t.name === tag));
+    }
+
+    /**
+     * 获取标签的静态路径参数，用于生成标签页面的路由，专门配合 [lang]/blogs/tag/[name].astro 使用
+     *
+     * @returns 返回所有标签的路径参数数组
+     * 返回格式：
+     * [
+     *   { params: { lang: 'zh-cn', name: 'typescript' } },
+     *   { params: { lang: 'en', name: 'javascript' } }
+     * ]
+     */
+    async getTagsStaticPaths() {
+        const debug = false;
+        const tags = await this.getTags();
+
+        const paths = tags.map((tag) => {
+            return {
+                params: {
+                    lang: tag.lang,
+                    name: tag.name,
+                },
+            };
+        });
+
+        if (debug) {
+            cosyLogger.array('所有的标签路径', paths);
+        }
+
+        return paths;
+    }
+
+    makeBlogCollection = (base: string) => {
+        return defineCollection({
+            loader: glob({
+                pattern: '**/*.{md,mdx}',
+                base,
+            }),
+            schema: z.object({
+                title: z.string(),
+                description: z.string().optional(),
+                tags: z.array(z.string()).optional(),
+                date: z.date().optional(),
+                draft: z.boolean().optional(),
+                hidden: z.boolean().optional(),
+                famous: z.boolean().optional(),
+                authors: z
+                    .array(
+                        z.object({
+                            name: z.string(),
+                            picture: z.string().optional(),
+                            url: z.string().optional(),
+                        })
+                    )
+                    .optional(),
+            }),
+        });
+    };
+}
+
+// 创建并导出单例实例
+export const blogRepo = new BlogRepo();

package/dist/src-astro/collection/repos/CourseRepo.ts

@@ -0,0 +1,137 @@
+import CourseDoc from '../entities/CourseDoc';
+import { defineCollection, getCollection, z, type CollectionEntry } from 'astro:content';
+import { BaseDB } from './BaseRepo';
+import { glob } from 'astro/loaders';
+
+export const COLLECTION_COURSE = 'courses' as const;
+export type CourseEntry = CollectionEntry<typeof COLLECTION_COURSE>;
+
+/**
+ * 课程数据库类，用于管理课程内容集合。
+ *
+ * 目录结构：
+ * ```
+ * courses/
+ * ├── zh-cn/                  # 中文版本
+ * │   ├── web-development/    # 课程1
+ * │   │   ├── index.md        # 课程文档
+ * │   │   ├── chapter1
+ * │   │   │   ├── index.md
+ * │   │   │   ├── content.md
+ * │   │   │   └── ...
+ * │   │   └── chapter2
+ * │   │       ├── index.md
+ * │   │       ├── content.md
+ * │   │       └── ...
+ * │   └── mobile-dev/        # 课程2
+ * │       ├── index.md
+ * │       └── ...
+ * └── en/                    # 英文版本
+ *     └── ...
+ * ```
+ * 
+ * 说明：
+ * - 如果希望单个课程可以作为 git 项目管理，考虑使用 LessonRepo 代替 CourseRepo
+ */
+class CourseRepo extends BaseDB<
+    typeof COLLECTION_COURSE,
+    CourseEntry,
+    CourseDoc
+> {
+    protected collectionName = COLLECTION_COURSE;
+
+    protected createDoc(entry: CourseEntry): CourseDoc {
+        return new CourseDoc(entry);
+    }
+
+    /**
+     * 获取指定语言的所有顶级课程，适用于在索引页面展示课程列表的情况
+     *
+     * @param lang - 语言代码
+     * @returns 返回指定语言的顶级课程数组
+     */
+    async allCoursesByLang(lang: string): Promise<CourseDoc[]> {
+        return await getCollection(COLLECTION_COURSE, ({ id }: { id: string }) => {
+            return id.startsWith(lang) && id.split('/').length === 2;
+        }).map((entry: CourseEntry) => new CourseDoc(entry));
+    }
+
+    /**
+     * 获取用于 Astro 静态路由生成的路径参数，专门配合 [lang]/courses/[...slug].astro 使用
+     *
+     * @returns 返回路径参数数组
+     */
+    async getStaticPaths(): Promise<
+        { params: { lang: string; slug: string } }[]
+    > {
+        const entries = await getCollection(COLLECTION_COURSE);
+        return entries.map((entry: CourseEntry) => {
+            const doc = new CourseDoc(entry);
+            return {
+                params: {
+                    lang: doc.getLang(),
+                    slug: doc.getSlug(),
+                },
+            };
+        });
+    }
+
+    /**
+     * 获取精选课程
+     *
+     * @param lang - 语言代码（如 'zh-cn', 'en'）
+     * @param count - 返回的课程数量（默认4个）
+     * @returns 返回精选课程文档数组
+     */
+    async getFamousCourses(lang: string, count: number = 4): Promise<CourseDoc[]> {
+        return (await this.allCoursesByLang(lang))
+            .filter((course) => course.isFamous())
+            .slice(0, count);
+    }
+
+    /**
+     * 获取指定语言的课程，并根据标签过滤
+     *
+     * @param lang - 语言代码（如 'zh-cn', 'en'）
+     * @param tag - 标签
+     * @returns 返回符合条件的课程文档数组
+     */
+    async getCoursesWithTag(lang: string, tag: string): Promise<CourseDoc[]> {
+        return (await this.allCoursesByLang(lang))
+            .filter((course) => course.hasTag(tag));
+    }
+
+    makeCourseCollection = (base: string) => {
+        return defineCollection({
+            loader: glob({
+                pattern: '**/*.{md,mdx}',
+                base,
+            }),
+            schema: z.object({
+                title: z.string().optional(),
+                description: z.string().optional(),
+                folder: z.boolean().optional(),
+                authors: z
+                    .array(
+                        z.object({
+                            name: z.string(),
+                            picture: z.string().optional(),
+                            url: z.string().optional(),
+                        })
+                    )
+                    .optional(),
+                date: z.date().optional(),
+                order: z.number().optional(),
+                badge: z.string().optional(),
+                draft: z.boolean().optional(),
+                hidden: z.boolean().optional(),
+                famous: z.boolean().optional(),
+                tags: z.array(z.string()).optional(),
+                category: z.string().optional(),
+            }),
+        });
+    };
+}
+
+// 创建并导出单例实例
+export const courseRepo = new CourseRepo();