@spfn/cms 0.1.0-alpha.88 → 0.2.0-beta.1

package/README.md

@@ -1,16 +1,17 @@
 # @spfn/cms
 
-Content Management System for Next.js with JSON-based labels and automatic database synchronization.
+Type-safe Content Management System for Next.js with automatic database synchronization and published cache.
 
 ## Features
 
-- 📁 JSON file-based labels
-- 🔄 Auto-sync to database
-- 🌐 50+ languages support
-- 🍪 Cookie-based locale management
-- 🔥 Hot reload during development
-- 💾 Published cache (17x faster)
-- 📝 Draft system & version control
+- 🎯 **Type-safe labels** - Full TypeScript support with autocomplete
+- 🔄 **Auto-sync** - Database synchronization on server startup
+- 🌐 **Multi-language** - Type-checked locale support
+- 🍪 **Smart locale detection** - Cookie-based with automatic fallback
+- 💾 **Published cache** - 17x faster queries (5ms vs 87ms)
+- 🎨 **Nested structure** - Organize labels hierarchically
+- 🔧 **Template variables** - Dynamic content with `{placeholder}` syntax
+- 📝 **Draft & versioning** - Version control and audit logs
 
 ## Installation
 
@@ -20,83 +21,431 @@ pnpm spfn add @spfn/cms
 
 ## Quick Start
 
-### 1. Create Label Files
+### 1. Define Labels & Configuration
 
-```json
-// src/lib/labels/home/hero.json
-{
-  "title": {
-    "key": "home.hero.title",
-    "defaultValue": {
-      "ko": "혁신적인 솔루션",
-      "en": "Innovative Solutions"
+```typescript
+// labels.ts
+import { defineLabelConfig, defineLabels, createCmsClient } from '@spfn/cms';
+
+// Configure locales
+export const labelConfig = defineLabelConfig({
+    locales: ['en', 'ko'] as const,
+    defaultLocale: 'ko',
+    fallbackLocale: 'en'
+});
+
+// Define labels with nested structure
+export const labelsDefinition = defineLabels({
+    home: {
+        hero: {
+            title: { en: "Welcome", ko: "환영합니다" },
+            subtitle: { en: "Start your journey", ko: "여정을 시작하세요" },
+            greeting: { en: "Hello {name}!", ko: "{name}님 안녕하세요!" }
+        },
+        cta: { en: "Get Started", ko: "시작하기" }
+    },
+    about: {
+        title: { en: "About Us", ko: "회사 소개" }
     }
-  }
-}
+});
+
+// Create client with API, getLabel, getLabels, and format
+export const { api, getLabel, getLabels, format } = createCmsClient(
+    labelsDefinition,
+    labelConfig
+);
 ```
 
 ### 2. Enable Auto-Sync
 
 ```typescript
-// src/server/server.config.ts
-import { initLabelSync } from '@spfn/cms/server';
+// server.config.ts
+import { defineServerConfig } from '@spfn/core/server';
+import { syncLabels } from '@spfn/cms/server';
+import { labelsDefinition } from './labels';
+
+
+// Option 1: Single definition
+export default defineServerConfig()
+    .lifecycle({
+        afterInfrastructure: async () => {
+            await syncLabels(labelsDefinition);
+        }
+    })
+    .build();
+
+// Option 2: Multiple definitions (organized in separate files)
+import { homeLabels } from './labels/home';
+import { aboutLabels } from './labels/about';
 
-export default {
-  beforeRoutes: async (app) => {
-    await initLabelSync({ verbose: true });
-  },
-} satisfies ServerConfig;
+export default defineServerConfig()
+    .lifecycle({
+        afterInfrastructure: async () => {
+            await syncLabels([homeLabels, aboutLabels]);
+        }
+    })
+    .build();
 ```
 
 ### 3. Use in Your App
 
-**Server Component:**
+**Server Component (Single Section):**
 
 ```typescript
-import { getSection } from '@spfn/cms/server';
+import { getLabel, format } from '@/labels';
 
 export default async function HomePage() {
-  const { t } = await getSection('home');
-  return <h1>{t('hero.title')}</h1>;
+    // Single section - direct access without section name
+    const label = await getLabel('home');
+
+    return (
+        <div>
+            <h1>{label.hero.title}</h1>
+            <p>{label.hero.subtitle}</p>
+            <button>{label.cta}</button>
+
+            {/* Template variables */}
+            <p>{format(label.hero.greeting, { name: 'John' })}</p>
+            {/* Output: "John님 안녕하세요!" */}
+        </div>
+    );
 }
 ```
 
-**Client Component:**
+**Server Component (Multiple Sections):**
+
+```typescript
+import { getLabels } from '@/labels';
+
+export default async function MultiSectionPage() {
+    // Multiple sections - with section names as keys
+    const labels = await getLabels(['home', 'about']);
+
+    return (
+        <div>
+            <h1>{labels.home.hero.title}</h1>
+            <p>{labels.about.title}</p>
+        </div>
+    );
+}
+```
+
+**Locale Management:**
 
 ```typescript
 'use client';
-import { useSection } from '@spfn/cms/client';
+import { setLocale } from '@spfn/cms/actions';
 
-export default function Nav() {
-  const { t } = useSection('layout', { autoLoad: true });
-  return <nav><a>{t('nav.about')}</a></nav>;
+export function LanguageSwitcher() {
+    return (
+        <div>
+            <button onClick={() => setLocale('ko')}>한국어</button>
+            <button onClick={() => setLocale('en')}>English</button>
+        </div>
+    );
 }
 ```
 
-## Documentation
+## Key Features
 
-📖 **[Full Documentation](../../docs/ecosystem/cms/index.md)**
+### 🎯 Type Safety
 
-- [Getting Started](../../docs/ecosystem/cms/getting-started.md) - Setup and configuration
-- [Label Sync Guide](../../docs/ecosystem/cms/label-sync.md) - Auto-sync options
-- [Advanced Features](../../docs/ecosystem/cms/advanced-features.md) - Breakpoints, value types, Draft Mode
-- [Locale Management](../../docs/ecosystem/cms/locale-management.md) - 50+ languages guide
-- [API Reference](../../docs/ecosystem/cms/api-reference.md) - Complete API docs
-- [Draft & Versioning](../../docs/ecosystem/cms/draft-versioning.md) - Version control & audit logs
+**Section Name Validation:**
 
-## Configuration
+```typescript
+// ✅ Valid section names are enforced at compile time
+const label = await getLabel('home'); // OK
+await getLabel('homee'); // ❌ Compile error: 'homee' is not a valid section
 
-```bash
-# .env.local
-SPFN_CMS_DEFAULT_LOCALE=ko
-SPFN_CMS_SUPPORTED_LOCALES=en,ko,ja
-SPFN_CMS_DETECT_BROWSER_LANGUAGE=true
+// ✅ getLabel returns direct access (no section wrapper)
+const homeLabel = await getLabel('home');
+homeLabel.hero.title; // OK - direct access
+homeLabel.cta; // OK
+
+// ✅ getLabels requires array and returns sections with names
+const labels = await getLabels(['home', 'about']);
+labels.home.hero.title; // OK
+labels.about.title; // OK
+labels.contact.email; // ❌ Compile error: 'contact' was not requested
+```
+
+**Property Access Validation:**
+
+```typescript
+// Single section - direct access
+const label = await getLabel('signup');
+
+// ✅ IDE autocomplete works perfectly
+label.title; // OK - direct access
+label.userName; // OK
+label.email; // OK
+
+// ❌ Typos are caught at compile time
+label.titlee; // ❌ Compile error
+label.userName; // ❌ Compile error (typo)
+
+// Multiple sections - with section names
+const labels = await getLabels(['home', 'about']);
+labels.home.hero.title; // OK
+labels.about.title; // OK
+```
+
+**API Distinction:**
+
+```typescript
+// getLabel: Single section, direct access
+const signup = await getLabel('signup');
+signup.title; // ✅ Direct access (cleaner!)
+
+// getLabels: Multiple sections, section names as keys
+const multi = await getLabels(['home', 'signup']);
+multi.home.title; // ✅ With section name
+multi.signup.userName; // ✅ With section name
+```
+
+### 🎨 Nested Structure
+
+```typescript
+defineLabels({
+    features: {
+        analytics: {
+            title: { en: "Analytics", ko: "분석" },
+            description: { en: "Track metrics", ko: "지표 추적" }
+        },
+        security: {
+            title: { en: "Security", ko: "보안" }
+        }
+    }
+});
+
+// Single section - direct access with nesting
+const label = await getLabel('features');
+label.analytics.title; // "분석" (auto locale, direct access!)
+label.analytics.description; // "지표 추적"
+label.security.title; // "보안"
+```
+
+### 🔧 Template Variables
+
+```typescript
+defineLabels({
+    home: {
+        welcome: {
+            en: "Welcome {name}, you have {count} messages",
+            ko: "{name}님, {count}개의 메시지가 있습니다"
+        }
+    }
+});
+
+const label = await getLabel('home');
+const text = label.welcome; // Direct access!
+
+format(text, { name: "John", count: 5 });
+// Output: "John님, 5개의 메시지가 있습니다"
+```
+
+### 🍪 Smart Locale Detection
+
+Automatic locale detection with priority:
+1. User's cookie (`cms-locale`)
+2. Config's `defaultLocale`
+3. Final fallback: `'en'`
+
+```typescript
+// User sets locale (saved to cookie)
+await setLocale('ko');
+
+// Automatically uses 'ko' locale
+const label = await getLabel('home');
+label.hero.title; // "환영합니다" (Korean)
+
+// Switch to English
+await setLocale('en');
+const label2 = await getLabel('home');
+label2.hero.title; // "Welcome" (English)
+```
+
+### 🔄 Auto-Sync
+
+Labels synchronize automatically on server startup:
+- ✅ Creates new labels
+- ✅ Updates changed labels (deep equality check)
+- ✅ Skips unchanged labels (performance)
+- ✅ Rebuilds published cache
+- ⚠️ Optionally removes orphaned labels
+
+## API Reference
+
+### createCmsClient()
+
+Factory function to create CMS client with API, getLabel, getLabels, and format utilities.
+
+```typescript
+const { api, getLabel, getLabels, format } = createCmsClient(labelsDefinition, labelConfig);
+```
+
+**Returns:**
+- `api` - API client for CMS routes
+- `getLabel(section)` - Fetch a single section (direct access)
+- `getLabels(sections)` - Fetch multiple sections (with section names)
+- `format(template, vars)` - Template variable substitution
+
+### getLabel()
+
+Fetch a **single section** from published cache with direct access (no section name wrapper).
+
+```typescript
+// Single section - direct access
+const label = await getLabel('home');
+label.hero.title; // Direct access without 'home.' prefix
+label.cta;
+```
+
+**Use when:**
+- You need labels from only ONE section
+- You want cleaner, direct access to properties
+- Most common use case for individual pages
+
+**Returns:** Labels directly without section name wrapper
+
+**Features:**
+- Auto locale detection (cookie → defaultLocale → 'en')
+- Direct property access (no section name)
+- Type-safe with IDE autocomplete
+- Merges published cache with defaults
+
+### getLabels()
+
+Fetch **multiple sections** from published cache with section names as keys.
+
+```typescript
+// Multiple sections - with section names
+const labels = await getLabels(['home', 'about']);
+labels.home.hero.title; // Access via section name
+labels.about.title;
+```
+
+**Use when:**
+- You need labels from MULTIPLE sections
+- You're building a page that uses multiple label groups
+
+**Returns:** Object with section names as keys
+
+**Features:**
+- Auto locale detection (cookie → defaultLocale → 'en')
+- Section filtering (only processes requested sections)
+- Type-safe: only requested sections available
+- Merges published cache with defaults
+
+**Performance:**
+- Only requested sections are processed (not entire labelsDefinition)
+- 10x faster when requesting specific sections
+- Reduces CPU and memory usage proportionally
+
+### format()
+
+Replace template variables in strings.
+
+```typescript
+format("Hello {name}!", { name: "John" }); // "Hello John!"
+format("{count} items", { count: 5 }); // "5 items"
+```
+
+**Syntax:** `{variableName}` - Supports strings and numbers
+
+### setLocale() / getLocale()
+
+Server actions for locale management (cookie-based).
+
+```typescript
+// Set user's preferred locale
+await setLocale('ko'); // Saves to 'cms-locale' cookie
+
+// Get current locale
+const locale = await getLocale(defaultLocale); // Returns: cookie → defaultLocale → 'en'
 ```
 
+**Cookie settings:**
+- Name: `cms-locale`
+- Max age: 1 year
+- HttpOnly, Secure (production), SameSite: lax
+
+### syncLabels()
+
+Synchronize labels to database (server-side only).
+
+```typescript
+await syncLabels(labelsDefinition, {
+    removeOrphaned: false, // Delete labels not in code
+    dryRun: false // Preview changes without applying
+});
+```
+
+**Returns:** `{ added, updated, removed, unchanged }`
+
+## Architecture
+
+### Database Schema
+
+```
+cms_labels (metadata)
+  ├─ id, key, section, type, defaultValue
+  └─ publishedVersion
+
+cms_label_values (actual content)
+  ├─ labelId, version, locale, breakpoint
+  └─ value (JSONB)
+
+cms_published_cache (performance)
+  ├─ section, locale, content (JSONB)
+  └─ version (for cache invalidation)
+
+cms_audit_logs (tracking)
+  └─ action, userId, changes, metadata
+```
+
+### Query Flow
+
+1. **getLabels()** → published_cache (single query, 5ms)
+2. **Fallback** → bindLocale(defaults)
+3. **Merge** → cache overrides defaults
+4. **Return** → type-safe nested object
+
+## Performance
+
+- **Published cache:** 5ms (vs 87ms with JOINs) - 17x faster
+- **N+1 prevention:** Bulk section queries with `inArray()`
+- **Section filtering:** Only requested sections processed (10x faster for selective access)
+- **Unchanged labels:** Skipped during sync (deep equality check)
+- **Client caching:** Version-based invalidation
+
+### Example: Large Scale
+
+```typescript
+// 10 sections with 100 labels each = 1,000 total labels
+const labelsDefinition = {
+    home: { /* 100 labels */ },
+    about: { /* 100 labels */ },
+    products: { /* 100 labels */ },
+    // ... 7 more sections
+};
+
+// Only request 'home' - direct access
+const label = await getLabel('home');
+
+// ✅ Performance: Processes only 100 labels (10% of total)
+// ❌ Without filtering: Would process all 1,000 labels
+```
+
+**Benefits:**
+- CPU usage: 10x reduction (100 vs 1,000 labels)
+- Memory usage: 10x reduction
+- Response time: Proportionally faster
+
 ## Development Status
 
 This package is currently in alpha. APIs may change.
 
 ## License
 
-MIT
+MIT

package/dist/actions.d.ts

@@ -1,2 +1,15 @@
-export { g as getLocale, a as getLocales, s as setLocale } from './actions-BEFWwQsh.js';
-export { L as LOCALE_COOKIE_KEY } from './locale.constants-BNkSdNP1.js';
+/**
+ * Set user's preferred locale in cookie
+ *
+ * @param locale - Language code (e.g., 'ko', 'en', 'ja')
+ */
+declare function setLocale(locale: string): Promise<void>;
+/**
+ * Get user's preferred locale from cookie
+ *
+ * @param defaultLocale - Default locale from labelConfig.defaultLocale
+ * @returns Language code (from cookie, or defaultLocale, or 'en')
+ */
+declare function getLocale(defaultLocale?: string): Promise<string>;
+
+export { getLocale, setLocale };

package/dist/actions.js

@@ -1,100 +1,26 @@
-// src/server/helpers/locale.actions.ts
-import { cookies, headers } from "next/headers.js";
+"use server";
 
-// src/server/config/cms.config.ts
-function getEnvVar(key, defaultValue) {
-  return process.env[key] || defaultValue;
-}
-function getEnvBoolean(key, defaultValue) {
-  const value = process.env[key];
-  if (value === void 0) return defaultValue;
-  return value === "true" || value === "1";
-}
-function loadConfigFromEnv() {
-  const defaultLocale = getEnvVar("SPFN_CMS_DEFAULT_LOCALE", "en");
-  const supportedLocalesStr = getEnvVar("SPFN_CMS_SUPPORTED_LOCALES", "en,ko");
-  const detectBrowserLanguage2 = getEnvBoolean("SPFN_CMS_DETECT_BROWSER_LANGUAGE", true);
-  const locales = supportedLocalesStr.split(",").map((locale) => locale.trim()).filter((locale) => locale.length > 0);
-  if (!locales.includes(defaultLocale)) {
-    locales.unshift(defaultLocale);
-  }
-  return {
-    defaultLocale,
-    locales,
-    supportedLocales: locales,
-    // backward compatibility
-    detectBrowserLanguage: detectBrowserLanguage2
-  };
-}
-var currentConfig = loadConfigFromEnv();
-function getCmsConfig() {
-  return currentConfig;
-}
-
-// src/lib/constants/locale.constants.ts
-var LOCALE_COOKIE_KEY = "spfn-locale";
-
-// src/server/helpers/locale.actions.ts
-async function detectBrowserLanguage() {
-  try {
-    const headersList = await headers();
-    const acceptLanguage = headersList.get("accept-language");
-    if (!acceptLanguage) {
-      return null;
-    }
-    const languages = acceptLanguage.split(",").map((lang) => {
-      const [code] = lang.split(";");
-      return code.split("-")[0].trim();
-    });
-    const config = getCmsConfig();
-    for (const lang of languages) {
-      if (config.locales.includes(lang)) {
-        return lang;
-      }
-    }
-    return null;
-  } catch (error) {
-    return null;
-  }
-}
-async function getLocale() {
-  const config = getCmsConfig();
-  const cookieStore = await cookies();
-  const cookieLocale = cookieStore.get(LOCALE_COOKIE_KEY)?.value;
-  if (cookieLocale && config.locales.includes(cookieLocale)) {
-    return cookieLocale;
-  }
-  if (config.detectBrowserLanguage) {
-    const browserLang = await detectBrowserLanguage();
-    if (browserLang) {
-      return browserLang;
-    }
-  }
-  return config.defaultLocale;
-}
+// src/actions.ts
+import { cookies } from "next/headers";
+var LOCALE_COOKIE_NAME = "cms-locale";
+var LOCALE_MAX_AGE = 365 * 24 * 60 * 60;
 async function setLocale(locale) {
-  const config = getCmsConfig();
-  if (!config.locales.includes(locale)) {
-    throw new Error(
-      `Unsupported locale: ${locale}. Supported locales: ${config.locales.join(", ")}`
-    );
-  }
   const cookieStore = await cookies();
-  cookieStore.set(LOCALE_COOKIE_KEY, locale, {
-    path: "/",
-    maxAge: 60 * 60 * 24 * 365,
-    // 1년
-    sameSite: "lax"
+  cookieStore.set(LOCALE_COOKIE_NAME, locale, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    maxAge: LOCALE_MAX_AGE,
+    path: "/"
   });
 }
-async function getLocales() {
-  const config = getCmsConfig();
-  return config.locales;
+async function getLocale(defaultLocale) {
+  const cookieStore = await cookies();
+  const localeCookie = cookieStore.get(LOCALE_COOKIE_NAME);
+  return localeCookie?.value ?? defaultLocale ?? "en";
 }
 export {
-  LOCALE_COOKIE_KEY,
   getLocale,
-  getLocales,
   setLocale
 };
 //# sourceMappingURL=actions.js.map