@reallukemanning/folio 1.0.0

package/src/lib/__tests__/sortByDate.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect } from 'vitest'
+import { sortByDate, type SortOrder } from '../sortByDate'
+import type { FolioProject } from '../../types'
+
+function createProject(overrides: Partial<FolioProject> = {}): FolioProject {
+  return {
+    id: 'test-id',
+    type: 'github',
+    status: 'active',
+    featured: false,
+    name: 'Test Project',
+    tagline: '',
+    description: '',
+    background: null,
+    why: null,
+    image: null,
+    struggles: [],
+    timeline: [],
+    posts: [],
+    stack: [],
+    links: {},
+    stats: null,
+    language: null,
+    languageColor: null,
+    createdAt: null,
+    updatedAt: null,
+    ...overrides,
+  }
+}
+
+describe('sortByDate', () => {
+  describe('empty array handling', () => {
+    it('should return empty array when input is empty', () => {
+      expect(sortByDate([])).toEqual([])
+    })
+
+    it('should return empty array with asc order when input is empty', () => {
+      expect(sortByDate([], 'asc')).toEqual([])
+    })
+  })
+
+  describe('sorting with updatedAt', () => {
+    it('should sort by updatedAt descending by default', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: '2024-06-15' }),
+        createProject({ id: '3', updatedAt: '2024-03-10' }),
+      ]
+
+      const result = sortByDate(projects)
+
+      expect(result.map(p => p.id)).toEqual(['2', '3', '1'])
+    })
+
+    it('should sort by updatedAt ascending when order is asc', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: '2024-06-15' }),
+        createProject({ id: '3', updatedAt: '2024-03-10' }),
+      ]
+
+      const result = sortByDate(projects, 'asc')
+
+      expect(result.map(p => p.id)).toEqual(['1', '3', '2'])
+    })
+  })
+
+  describe('fallback to createdAt', () => {
+    it('should fallback to createdAt when updatedAt is missing', () => {
+      const projects = [
+        createProject({ id: '1', createdAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: '2024-06-15', createdAt: '2024-01-01' }),
+        createProject({ id: '3', createdAt: '2024-03-10' }),
+      ]
+
+      const result = sortByDate(projects, 'desc')
+
+      expect(result.map(p => p.id)).toEqual(['2', '3', '1'])
+    })
+
+    it('should use createdAt when updatedAt is null', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: null, createdAt: '2024-05-01' }),
+        createProject({ id: '2', updatedAt: '2024-03-01', createdAt: '2024-01-01' }),
+      ]
+
+      const result = sortByDate(projects, 'desc')
+
+      expect(result.map(p => p.id)).toEqual(['1', '2'])
+    })
+  })
+
+  describe('handling missing dates', () => {
+    it('should place projects without dates at the beginning in desc order', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: null, createdAt: null }),
+        createProject({ id: '3', updatedAt: '2024-06-01' }),
+      ]
+
+      const result = sortByDate(projects, 'desc')
+
+      expect(result.map(p => p.id)).toEqual(['2', '3', '1'])
+    })
+
+    it('should place projects without dates at the end in asc order', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: null, createdAt: null }),
+        createProject({ id: '3', updatedAt: '2024-06-01' }),
+      ]
+
+      const result = sortByDate(projects, 'asc')
+
+      expect(result.map(p => p.id)).toEqual(['1', '3', '2'])
+    })
+
+    it('should handle all projects without dates', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: null, createdAt: null }),
+        createProject({ id: '2', updatedAt: null, createdAt: null }),
+      ]
+
+      const result = sortByDate(projects)
+
+      expect(result).toHaveLength(2)
+    })
+
+    it('should return 0 for comparison when both dates are missing', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: null, createdAt: null }),
+        createProject({ id: '2', updatedAt: null, createdAt: null }),
+      ]
+
+      const result = sortByDate(projects, 'desc')
+
+      expect(result).toHaveLength(2)
+    })
+  })
+
+  describe('date parsing', () => {
+    it('should correctly parse ISO date strings', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-12-31T23:59:59Z' }),
+        createProject({ id: '2', updatedAt: '2024-01-01T00:00:00Z' }),
+      ]
+
+      const result = sortByDate(projects, 'desc')
+
+      expect(result.map(p => p.id)).toEqual(['1', '2'])
+    })
+
+    it('should handle different date formats', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-06-15' }),
+        createProject({ id: '2', updatedAt: '2024-03-20' }),
+        createProject({ id: '3', updatedAt: '2024-01-05' }),
+      ]
+
+      const result = sortByDate(projects, 'asc')
+
+      expect(result.map(p => p.id)).toEqual(['3', '2', '1'])
+    })
+  })
+
+  describe('immutability', () => {
+    it('should not mutate the original array', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: '2024-06-01' }),
+      ]
+
+      const originalOrder = projects.map(p => p.id)
+      sortByDate(projects, 'desc')
+
+      expect(projects.map(p => p.id)).toEqual(originalOrder)
+    })
+
+    it('should return a new array instance', () => {
+      const projects = [createProject({ updatedAt: '2024-01-01' })]
+
+      const result = sortByDate(projects)
+
+      expect(result).not.toBe(projects)
+    })
+  })
+
+  describe('order parameter types', () => {
+    it('should accept asc order', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-06-01' }),
+        createProject({ id: '2', updatedAt: '2024-01-01' }),
+      ]
+
+      const result = sortByDate(projects, 'asc' as SortOrder)
+
+      expect(result.map(p => p.id)).toEqual(['2', '1'])
+    })
+
+    it('should accept desc order', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: '2024-06-01' }),
+      ]
+
+      const result = sortByDate(projects, 'desc' as SortOrder)
+
+      expect(result.map(p => p.id)).toEqual(['2', '1'])
+    })
+
+    it('should default to desc when order is not provided', () => {
+      const projects = [
+        createProject({ id: '1', updatedAt: '2024-01-01' }),
+        createProject({ id: '2', updatedAt: '2024-06-01' }),
+      ]
+
+      const result = sortByDate(projects)
+
+      expect(result.map(p => p.id)).toEqual(['2', '1'])
+    })
+  })
+})

package/src/lib/__tests__/sortByName.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect } from 'vitest'
+import { sortByName } from '../sortByName'
+import type { FolioProject } from '../../types'
+
+function createProject(overrides: Partial<FolioProject> = {}): FolioProject {
+  return {
+    id: 'test-id',
+    type: 'github',
+    status: 'active',
+    featured: false,
+    name: 'Test Project',
+    tagline: '',
+    description: '',
+    background: null,
+    why: null,
+    image: null,
+    struggles: [],
+    timeline: [],
+    posts: [],
+    stack: [],
+    links: {},
+    stats: null,
+    language: null,
+    languageColor: null,
+    createdAt: null,
+    updatedAt: null,
+    ...overrides,
+  }
+}
+
+describe('sortByName', () => {
+  describe('empty array handling', () => {
+    it('should return empty array when input is empty', () => {
+      expect(sortByName([])).toEqual([])
+    })
+
+    it('should return empty array with desc order when input is empty', () => {
+      expect(sortByName([], 'desc')).toEqual([])
+    })
+  })
+
+  describe('case-insensitive sorting', () => {
+    it('should sort names case-insensitively by default (asc)', () => {
+      const projects = [
+        createProject({ id: '1', name: 'zebra' }),
+        createProject({ id: '2', name: 'Apple' }),
+        createProject({ id: '3', name: 'BANANA' }),
+      ]
+
+      const result = sortByName(projects)
+
+      expect(result.map(p => p.id)).toEqual(['2', '3', '1'])
+    })
+
+    it('should sort names case-insensitively in desc order', () => {
+      const projects = [
+        createProject({ id: '1', name: 'apple' }),
+        createProject({ id: '2', name: 'Zebra' }),
+        createProject({ id: '3', name: 'Banana' }),
+      ]
+
+      const result = sortByName(projects, 'desc')
+
+      expect(result.map(p => p.id)).toEqual(['2', '3', '1'])
+    })
+
+    it('should handle mixed case names correctly', () => {
+      const projects = [
+        createProject({ id: '1', name: 'React' }),
+        createProject({ id: '2', name: 'react' }),
+        createProject({ id: '3', name: 'REACT' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result).toHaveLength(3)
+    })
+  })
+
+  describe('handling missing names', () => {
+    it('should place projects with null names at the end in asc order', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Beta' }),
+        createProject({ id: '2', name: null as unknown as string }),
+        createProject({ id: '3', name: 'Alpha' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result[result.length - 1].id).toBe('2')
+      expect(result.slice(0, 2).map(p => p.id)).toEqual(['3', '1'])
+    })
+
+    it('should place projects with null names at the end in desc order', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Beta' }),
+        createProject({ id: '2', name: null as unknown as string }),
+        createProject({ id: '3', name: 'Alpha' }),
+      ]
+
+      const result = sortByName(projects, 'desc')
+
+      expect(result[result.length - 1].id).toBe('2')
+    })
+
+    it('should handle all projects with null names', () => {
+      const projects = [
+        createProject({ id: '1', name: null as unknown as string }),
+        createProject({ id: '2', name: null as unknown as string }),
+      ]
+
+      const result = sortByName(projects)
+
+      expect(result).toHaveLength(2)
+    })
+
+    it('should return 0 for comparison when both names are null', () => {
+      const projects = [
+        createProject({ id: '1', name: null as unknown as string }),
+        createProject({ id: '2', name: null as unknown as string }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result).toHaveLength(2)
+    })
+  })
+
+  describe('alphabetical sorting', () => {
+    it('should sort names alphabetically in asc order', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Zulu' }),
+        createProject({ id: '2', name: 'Alpha' }),
+        createProject({ id: '3', name: 'Mike' }),
+        createProject({ id: '4', name: 'Charlie' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result.map(p => p.name)).toEqual(['Alpha', 'Charlie', 'Mike', 'Zulu'])
+    })
+
+    it('should sort names reverse-alphabetically in desc order', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Alpha' }),
+        createProject({ id: '2', name: 'Zulu' }),
+        createProject({ id: '3', name: 'Mike' }),
+      ]
+
+      const result = sortByName(projects, 'desc')
+
+      expect(result.map(p => p.name)).toEqual(['Zulu', 'Mike', 'Alpha'])
+    })
+
+    it('should handle names with numbers (lexical sorting)', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Project 2' }),
+        createProject({ id: '2', name: 'Project 10' }),
+        createProject({ id: '3', name: 'Project 1' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result.map(p => p.id)).toEqual(['3', '2', '1'])
+    })
+  })
+
+  describe('special characters and unicode', () => {
+    it('should handle names with special characters', () => {
+      const projects = [
+        createProject({ id: '1', name: '@project' }),
+        createProject({ id: '2', name: 'A-project' }),
+        createProject({ id: '3', name: '_project' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result).toHaveLength(3)
+    })
+
+    it('should handle unicode characters', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Über' }),
+        createProject({ id: '2', name: 'Apple' }),
+        createProject({ id: '3', name: 'Äpfel' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result.map(p => p.id)).toEqual(['3', '2', '1'])
+    })
+  })
+
+  describe('immutability', () => {
+    it('should not mutate the original array', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Zulu' }),
+        createProject({ id: '2', name: 'Alpha' }),
+      ]
+
+      const originalOrder = projects.map(p => p.id)
+      sortByName(projects, 'asc')
+
+      expect(projects.map(p => p.id)).toEqual(originalOrder)
+    })
+
+    it('should return a new array instance', () => {
+      const projects = [createProject({ name: 'Test' })]
+
+      const result = sortByName(projects)
+
+      expect(result).not.toBe(projects)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle duplicate names', () => {
+      const projects = [
+        createProject({ id: '1', name: 'Project' }),
+        createProject({ id: '2', name: 'Project' }),
+        createProject({ id: '3', name: 'Project' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result).toHaveLength(3)
+    })
+
+    it('should handle empty string names', () => {
+      const projects = [
+        createProject({ id: '1', name: '' }),
+        createProject({ id: '2', name: 'Alpha' }),
+      ]
+
+      const result = sortByName(projects, 'asc')
+
+      expect(result[result.length - 1].id).toBe('1')
+    })
+
+    it('should handle single project', () => {
+      const projects = [createProject({ name: 'Solo' })]
+
+      const result = sortByName(projects)
+
+      expect(result).toHaveLength(1)
+      expect(result[0].name).toBe('Solo')
+    })
+  })
+})

package/src/lib/__tests__/sortByStars.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from 'vitest'
+import { sortByStars } from '../sortByStars'
+import type { FolioProject } from '../../types'
+
+function createProject(overrides: Partial<FolioProject> = {}): FolioProject {
+  return {
+    id: 'test-id',
+    type: 'github',
+    status: 'active',
+    featured: false,
+    name: 'Test Project',
+    tagline: '',
+    description: '',
+    background: null,
+    why: null,
+    image: null,
+    struggles: [],
+    timeline: [],
+    posts: [],
+    stack: [],
+    links: {},
+    stats: null,
+    language: null,
+    languageColor: null,
+    createdAt: null,
+    updatedAt: null,
+    ...overrides,
+  }
+}
+
+describe('sortByStars', () => {
+  describe('empty array handling', () => {
+    it('should return empty array when input is empty', () => {
+      expect(sortByStars([])).toEqual([])
+    })
+
+    it('should return empty array with asc order when input is empty', () => {
+      expect(sortByStars([], 'asc')).toEqual([])
+    })
+  })
+
+  describe('sorting GitHub projects by stars', () => {
+    it('should sort GitHub projects by stars descending by default', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { stars: 100 } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 500 } }),
+        createProject({ id: '3', type: 'github', stats: { stars: 250 } }),
+      ]
+
+      const result = sortByStars(projects)
+
+      expect(result.map(p => p.id)).toEqual(['2', '3', '1'])
+    })
+
+    it('should sort GitHub projects by stars ascending when order is asc', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { stars: 100 } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 500 } }),
+        createProject({ id: '3', type: 'github', stats: { stars: 250 } }),
+      ]
+
+      const result = sortByStars(projects, 'asc')
+
+      expect(result.map(p => p.id)).toEqual(['1', '3', '2'])
+    })
+  })
+
+  describe('handling non-GitHub projects', () => {
+    it('should treat non-GitHub projects as having 0 stars', () => {
+      const projects = [
+        createProject({ id: '1', type: 'npm', stats: { downloads: '1000' } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 500 } }),
+        createProject({ id: '3', type: 'manual' }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result[0].id).toBe('2')
+      expect(result.filter(p => p.type !== 'github').every(p => result.indexOf(p) > 0)).toBe(true)
+    })
+
+    it('should place non-GitHub projects at the end in desc order', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { stars: 100 } }),
+        createProject({ id: '2', type: 'npm' }),
+        createProject({ id: '3', type: 'github', stats: { stars: 500 } }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result[result.length - 1].type).toBe('npm')
+    })
+  })
+
+  describe('handling missing stats', () => {
+    it('should handle GitHub projects without stats', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: null }),
+        createProject({ id: '2', type: 'github', stats: { stars: 500 } }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result[0].id).toBe('2')
+      expect(result[1].id).toBe('1')
+    })
+
+    it('should handle GitHub projects with stats but missing stars', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { forks: 10 } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 500 } }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result[0].id).toBe('2')
+    })
+
+    it('should handle all projects with 0 stars', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { stars: 0 } }),
+        createProject({ id: '2', type: 'npm' }),
+        createProject({ id: '3', type: 'github', stats: null }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result).toHaveLength(3)
+    })
+
+    it('should return 0 for comparison when both projects have 0 stars', () => {
+      const projects = [
+        createProject({ id: '1', type: 'npm' }),
+        createProject({ id: '2', type: 'manual' }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result).toHaveLength(2)
+    })
+  })
+
+  describe('mixed project types', () => {
+    it('should correctly sort mixed project types (only github counts stars)', () => {
+      const projects = [
+        createProject({ id: '1', type: 'npm', stats: { downloads: '1000' } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 100 } }),
+        createProject({ id: '3', type: 'product-hunt', stats: { upvotes: 50 } }),
+        createProject({ id: '4', type: 'github', stats: { stars: 500 } }),
+        createProject({ id: '5', type: 'hybrid', stats: { stars: 250 } }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result[0].id).toBe('4')
+      expect(result[1].id).toBe('2')
+      expect(result.filter(p => p.type !== 'github').every(p => result.indexOf(p) > 1)).toBe(true)
+    })
+  })
+
+  describe('immutability', () => {
+    it('should not mutate the original array', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { stars: 100 } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 500 } }),
+      ]
+
+      const originalOrder = projects.map(p => p.id)
+      sortByStars(projects, 'desc')
+
+      expect(projects.map(p => p.id)).toEqual(originalOrder)
+    })
+
+    it('should return a new array instance', () => {
+      const projects = [createProject({ type: 'github', stats: { stars: 100 } })]
+
+      const result = sortByStars(projects)
+
+      expect(result).not.toBe(projects)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle very large star counts', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { stars: 1000000 } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 500 } }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result.map(p => p.id)).toEqual(['1', '2'])
+    })
+
+    it('should handle projects with same star count', () => {
+      const projects = [
+        createProject({ id: '1', type: 'github', stats: { stars: 100 } }),
+        createProject({ id: '2', type: 'github', stats: { stars: 100 } }),
+      ]
+
+      const result = sortByStars(projects, 'desc')
+
+      expect(result).toHaveLength(2)
+    })
+  })
+})

package/src/lib/defineProjects.ts

@@ -0,0 +1,5 @@
+import type { FolioProjectInput } from '../types'
+
+export function defineProjects(projects: FolioProjectInput[]): FolioProjectInput[] {
+  return projects
+}

package/src/lib/filterByFeatured.ts

@@ -0,0 +1,16 @@
+import type { FolioProject } from '../types'
+
+export function filterByFeatured(
+  projects: FolioProject[],
+  featured: boolean | null | undefined
+): FolioProject[] {
+  if (projects.length === 0) {
+    return []
+  }
+
+  if (featured === null || featured === undefined) {
+    return [...projects]
+  }
+
+  return projects.filter(project => project.featured === featured)
+}