@secorto/i18n 0.0.4 → 0.1.0

package/LICENSE

@@ -0,0 +1,8 @@
+# MIT License (MIT)
+
+Copyright (c) 2023 Sergio Orozco Torres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.d.mts

@@ -77,6 +77,7 @@ declare function isMissing<L extends string>(link: TranslationLink<L>): link is
  * @throws {Error} If `links` is empty or if no accessible link exists.
  */
 declare function resolveDefaultAccessibleLink<L extends string>(links: TranslationLink<L>[], defaultLang: L): AccessibleTranslationLink<L>;
+declare function createAvailableLinks<L extends string>(locales: Locales<L>, getHref: (locale: L) => string): AvailableLink<L>[];
 //#endregion
 //#region src/core/standalone.d.ts
 /**
@@ -145,7 +146,7 @@ interface SectionRoutes<Section extends string, Language extends string> {
   /**
    * Returns the configured section identifiers.
    */
-  getSections(): Section[];
+  getSections(): readonly Section[];
   /**
    * Returns the localized slug for a section.
    *
@@ -171,6 +172,15 @@ interface SectionRoutes<Section extends string, Language extends string> {
    * @returns Full URL for the entry.
    */
   getEntryURL(section: Section, locale: Language, slug: string): string;
+  /**
+   * Returns the localized URL for a tag page inside a section.
+   *
+   * @param section Section identifier.
+   * @param locale Locale identifier.
+   * @param tag Tag name.
+   * @returns Full URL for the tag page.
+   */
+  getEntryTagURL(section: Section, locale: Language, tag: string): string;
 }
 /**
  * Constructs a nominal SectionRoutes value from a raw SectionDictionary.
@@ -209,11 +219,16 @@ interface LocalizedEntry<TEntry, L extends string> {
  * @template E - The type of the content (e.g., { title: string, body: string }).
  * @template C - The section of the application (e.g., 'blog', 'docs').
  */
-type TranslationIndex<L extends string, TEntry> = Record<string, Partial<Record<L, LocalizedEntry<TEntry, L>>>>;
+type TranslationGroup<L extends string, TEntry> = Partial<Record<L, LocalizedEntry<TEntry, L>>>;
+type TranslationIndex<L extends string, TEntry> = Partial<Record<string, TranslationGroup<L, TEntry>>>;
 /**
  * Builds a translation index from an array of localized entries.
  * The index groups entries by their translation key and locale.
  * If duplicate entries for the same translation key and locale are found, an error is thrown.
+ *
+ * Invariant: a key is only inserted into the map after at least one locale
+ * has been assigned to it. An empty group is therefore an invalid state.
+ *
  * @template E - The type of the content (e.g., { title: string, body: string }).
  * @template C - The section of the application (e.g., 'blog', 'docs').
  * @template L - The language code (e.g., 'es', 'en').
@@ -252,7 +267,7 @@ type DetailPath<C extends string, L extends string, TEntry extends GenericCollec
   props: {
     entry: LocalizedEntry<TEntry, L>;
     section: C;
-    siblings: TranslationIndex<L, TEntry>[string];
+    siblings: NonNullable<TranslationIndex<L, TEntry>[string]>;
   };
 };
 /**
@@ -296,4 +311,16 @@ declare function getStaticPathsEntries<C extends string, E extends object, L ext
  */
 declare function createDetailTranslationLinks<C extends string, L extends string, TEntry extends GenericCollectionEntry<C, object>>(siblings: Partial<Record<L, LocalizedEntry<TEntry, L>>>, sectionRoutes: SectionRoutes<C, L>, locales: Locales<L>): TranslationLink<L>[];
 //#endregion
-export { AccessibleTranslationLink, AvailableLink, DetailPath, DraftLink, GenericCollectionEntry, Locales, LocalizedEntry, MissingLink, SectionDictionary, SectionRoutes, StandalonePageEntry, StandalonePageIndex, TranslationIndex, TranslationLink, adaptToLocalizedEntry, availableLink, createDetailTranslationLinks, createLocales, createSectionRoutes, createStandalonePageLinks, createTranslationIndex, draftLink, extractCleanId, getStaticPathsEntries, isAccessible, isAvailable, isDraft, isMissing, missingLink, resolveDefaultAccessibleLink, resolveTranslationKey };
+//#region src/section/list-paths.d.ts
+interface SectionPath<TLocale extends string, TSection extends string> {
+  params: {
+    locale: TLocale;
+    section: string;
+  };
+  props: {
+    section: TSection;
+  };
+}
+declare function getStaticPathsSections<C extends string, L extends string>(routes: SectionRoutes<C, L>, allowedLocales: Locales<L>): Promise<SectionPath<L, C>[]>;
+//#endregion
+export { AccessibleTranslationLink, AvailableLink, DetailPath, DraftLink, GenericCollectionEntry, Locales, LocalizedEntry, MissingLink, SectionDictionary, SectionPath, SectionRoutes, StandalonePageEntry, StandalonePageIndex, TranslationGroup, TranslationIndex, TranslationLink, adaptToLocalizedEntry, availableLink, createAvailableLinks, createDetailTranslationLinks, createLocales, createSectionRoutes, createStandalonePageLinks, createTranslationIndex, draftLink, extractCleanId, getStaticPathsEntries, getStaticPathsSections, isAccessible, isAvailable, isDraft, isMissing, missingLink, resolveDefaultAccessibleLink, resolveTranslationKey };

package/dist/index.mjs

@@ -90,6 +90,13 @@ function resolveDefaultAccessibleLink(links, defaultLang) {
 	if (firstDraft) return firstDraft;
 	throw new Error("resolveDefaultAccessibleLink: expected at least one accessible link");
 }
+function createAvailableLinks(locales, getHref) {
+	return locales.all.map((locale) => ({
+		type: "available",
+		href: getHref(locale),
+		locale
+	}));
+}
 //#endregion
 //#region src/core/extract-id.ts
 /**
@@ -155,7 +162,8 @@ function createStandalonePageLinks(path, translationKey, index, locales) {
 */
 function createSectionRoutes(routes) {
 	const seen = /* @__PURE__ */ new Map();
-	for (const section of Object.keys(routes)) {
+	const sections = Object.freeze(Object.keys(routes));
+	for (const section of sections) {
 		const localized = routes[section];
 		for (const locale of Object.keys(localized)) {
 			const slug = localized[locale];
@@ -167,16 +175,20 @@ function createSectionRoutes(routes) {
 			seen.set(key, section);
 		}
 	}
-	const getSections = () => Object.keys(routes);
+	for (const section of sections) Object.freeze(routes[section]);
+	Object.freeze(routes);
+	const getSections = () => sections;
 	const getSectionRoute = (section, locale) => routes[section][locale];
 	const getSectionURL = (section, locale) => `/${locale}/${getSectionRoute(section, locale)}`;
+	const getEntryTagURL = (section, locale, tag) => `${getSectionURL(section, locale)}/tags/${encodeURIComponent(tag)}`;
 	const getEntryURL = (section, locale, slug) => `${getSectionURL(section, locale)}/${slug}`;
 	return {
 		routes,
 		getSections,
 		getSectionRoute,
 		getSectionURL,
-		getEntryURL
+		getEntryURL,
+		getEntryTagURL
 	};
 }
 //#endregion
@@ -185,6 +197,10 @@ function createSectionRoutes(routes) {
 * Builds a translation index from an array of localized entries.
 * The index groups entries by their translation key and locale.
 * If duplicate entries for the same translation key and locale are found, an error is thrown.
+*
+* Invariant: a key is only inserted into the map after at least one locale
+* has been assigned to it. An empty group is therefore an invalid state.
+*
 * @template E - The type of the content (e.g., { title: string, body: string }).
 * @template C - The section of the application (e.g., 'blog', 'docs').
 * @template L - The language code (e.g., 'es', 'en').
@@ -199,7 +215,7 @@ function createTranslationIndex(entries) {
 		const locale = entry.locale;
 		let group = map.get(key);
 		if (!group) {
-			group = {};
+			group = Object.create(null);
 			map.set(key, group);
 		} else if (locale in group) throw new Error(`Duplicate translation for key "${key}" and locale "${locale}"`);
 		group[locale] = entry;
@@ -263,18 +279,22 @@ async function getStaticPathsEntries(routes, fetchCollection, allowedLocales) {
 	for (const sectionKey of routes.getSections()) {
 		const localizedEntries = (await fetchCollection(sectionKey)).map((entry) => adaptToLocalizedEntry(entry, allowedLocales));
 		const index = createTranslationIndex(localizedEntries);
-		for (const localized of localizedEntries) allPaths.push({
-			params: {
-				locale: localized.locale,
-				section: routes.getSectionRoute(sectionKey, localized.locale),
-				id: localized.cleanId
-			},
-			props: {
-				entry: localized,
-				section: sectionKey,
-				siblings: index[localized.translationKey]
-			}
-		});
+		for (const localized of localizedEntries) {
+			const siblings = index[localized.translationKey];
+			if (!siblings || Object.keys(siblings).length === 0) throw new Error(`Missing translation group for key "${localized.translationKey}"`);
+			allPaths.push({
+				params: {
+					locale: localized.locale,
+					section: routes.getSectionRoute(sectionKey, localized.locale),
+					id: localized.cleanId
+				},
+				props: {
+					entry: localized,
+					section: sectionKey,
+					siblings
+				}
+			});
+		}
 	}
 	return allPaths;
 }
@@ -301,4 +321,17 @@ function createDetailTranslationLinks(siblings, sectionRoutes, locales) {
 	});
 }
 //#endregion
-export { adaptToLocalizedEntry, availableLink, createDetailTranslationLinks, createLocales, createSectionRoutes, createStandalonePageLinks, createTranslationIndex, draftLink, extractCleanId, getStaticPathsEntries, isAccessible, isAvailable, isDraft, isMissing, missingLink, resolveDefaultAccessibleLink, resolveTranslationKey };
+//#region src/section/list-paths.ts
+async function getStaticPathsSections(routes, allowedLocales) {
+	const allPaths = [];
+	for (const sectionKey of routes.getSections()) for (const locale of allowedLocales.all) allPaths.push({
+		params: {
+			locale,
+			section: routes.getSectionRoute(sectionKey, locale)
+		},
+		props: { section: sectionKey }
+	});
+	return allPaths;
+}
+//#endregion
+export { adaptToLocalizedEntry, availableLink, createAvailableLinks, createDetailTranslationLinks, createLocales, createSectionRoutes, createStandalonePageLinks, createTranslationIndex, draftLink, extractCleanId, getStaticPathsEntries, getStaticPathsSections, isAccessible, isAvailable, isDraft, isMissing, missingLink, resolveDefaultAccessibleLink, resolveTranslationKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secorto/i18n",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "private": false,
   "sideEffects": false,
   "description": "Framework-agnostic i18n primitive",
@@ -41,13 +41,6 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "clean": "rimraf dist",
-    "test": "vitest --run",
-    "test:unit": "vitest",
-    "test:unit:watch": "vitest --watch"
-  },
   "devDependencies": {
     "vitest": "^4.1.10"
   },
@@ -55,5 +48,12 @@
     "entry": [
       "src/index.ts"
     ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rimraf dist",
+    "test": "vitest --run",
+    "test:unit": "vitest",
+    "test:unit:watch": "vitest --watch"
   }
-}
+}

package/src/section/detail-path.ts

@@ -1,14 +1,16 @@
-import { Locales } from '../core'
+import type { Locales } from '../core'
 import {
   createTranslationIndex,
+} from './translation-index'
+import type {
   LocalizedEntry,
   TranslationIndex,
 } from './translation-index'
 import {
   adaptToLocalizedEntry,
-  GenericCollectionEntry,
 } from './entry-adapter'
-import { SectionRoutes } from './routes'
+import type { GenericCollectionEntry } from './entry-adapter'
+import type { SectionRoutes } from './routes'
 
 export type DetailPath<
   C extends string,
@@ -23,7 +25,7 @@ export type DetailPath<
   props: {
     entry: LocalizedEntry<TEntry, L>
     section: C
-    siblings: TranslationIndex<L, TEntry>[string]
+    siblings: NonNullable<TranslationIndex<L, TEntry>[string]>
   }
 }
 
@@ -76,6 +78,14 @@ export async function getStaticPathsEntries<
     const index = createTranslationIndex(localizedEntries)
 
     for (const localized of localizedEntries) {
+      const siblings = index[localized.translationKey]
+
+      if (!siblings || Object.keys(siblings).length === 0) {
+        throw new Error(
+          `Missing translation group for key "${localized.translationKey}"`,
+        )
+      }
+
       allPaths.push({
         params: {
           locale: localized.locale,
@@ -85,7 +95,7 @@ export async function getStaticPathsEntries<
         props: {
           entry: localized,
           section: sectionKey,
-          siblings: index[localized.translationKey],
+          siblings,
         },
       })
     }

package/src/section/details-links.ts

@@ -1,7 +1,8 @@
-import { availableLink, draftLink, Locales, missingLink, TranslationLink } from "../core"
-import { GenericCollectionEntry } from "./entry-adapter"
-import { SectionRoutes } from "./routes"
-import { LocalizedEntry } from "./translation-index"
+import { availableLink, draftLink, missingLink } from '../core'
+import type { Locales, TranslationLink } from '../core'
+import type { GenericCollectionEntry } from './entry-adapter'
+import type { SectionRoutes } from './routes'
+import type { LocalizedEntry } from './translation-index'
 
 /**
  * Creates translation links for all supported locales.

package/src/section/entry-adapter.ts

@@ -1,5 +1,6 @@
-import { extractCleanId, Locales } from '../core'
-import { LocalizedEntry } from './translation-index'
+import { extractCleanId } from '../core'
+import type { Locales } from '../core'
+import type { LocalizedEntry } from './translation-index'
 
 export interface GenericCollectionEntry<
   C extends string,

package/src/section/routes.ts

@@ -31,7 +31,7 @@ export interface SectionRoutes<
   /**
    * Returns the configured section identifiers.
    */
-  getSections(): Section[]
+  getSections(): readonly Section[]
 
   /**
    * Returns the localized slug for a section.
@@ -84,8 +84,9 @@ export function createSectionRoutes<
   routes: SectionDictionary<Section, Language, string>
 ): SectionRoutes<Section, Language> {
   const seen = new Map<string, Section>()
+  const sections = Object.freeze(Object.keys(routes) as Section[])
 
-  for (const section of Object.keys(routes) as Section[]) {
+  for (const section of sections) {
     const localized = routes[section]
 
     for (const locale of Object.keys(localized) as Language[]) {
@@ -103,7 +104,13 @@ export function createSectionRoutes<
     }
   }
 
-  const getSections = (): Section[] => Object.keys(routes) as Section[]
+  // Enforce runtime immutability for the value object invariants.
+  for (const section of sections) {
+    Object.freeze(routes[section])
+  }
+  Object.freeze(routes)
+
+  const getSections = (): readonly Section[] => sections
 
   const getSectionRoute = (section: Section, locale: Language): string =>
     routes[section][locale]

package/src/section/translation-index.ts

@@ -21,18 +21,24 @@ export interface LocalizedEntry<
  * @template E - The type of the content (e.g., { title: string, body: string }).
  * @template C - The section of the application (e.g., 'blog', 'docs').
  */
+export type TranslationGroup<
+  L extends string,
+  TEntry,
+> = Partial<Record<L, LocalizedEntry<TEntry, L>>>
+
 export type TranslationIndex<
   L extends string,
   TEntry
-> = Record<
-  string,
-  Partial<Record<L, LocalizedEntry<TEntry, L>>>
->
+> = Partial<Record<string, TranslationGroup<L, TEntry>>>
 
 /**
  * Builds a translation index from an array of localized entries.
  * The index groups entries by their translation key and locale.
  * If duplicate entries for the same translation key and locale are found, an error is thrown.
+ *
+ * Invariant: a key is only inserted into the map after at least one locale
+ * has been assigned to it. An empty group is therefore an invalid state.
+ *
  * @template E - The type of the content (e.g., { title: string, body: string }).
  * @template C - The section of the application (e.g., 'blog', 'docs').
  * @template L - The language code (e.g., 'es', 'en').
@@ -46,17 +52,16 @@ export function createTranslationIndex<
 >(
   entries: readonly LocalizedEntry<TEntry, L>[]
 ): TranslationIndex<L, TEntry> {
-  // Using map to safely mutate internally without lying to TypeScript
-  const map = new Map<string, Partial<Record<L, LocalizedEntry<TEntry, L>>>>()
+  // Using map to safely mutate internally without lying to TypeScript.
+  const map = new Map<string, TranslationGroup<L, TEntry>>()
 
   for (const entry of entries) {
     const key = entry.translationKey
     const locale = entry.locale
 
-    // Get or create the group for this key
     let group = map.get(key)
     if (!group) {
-      group = {}
+      group = Object.create(null) as TranslationGroup<L, TEntry>
       map.set(key, group)
     } else if (locale in group) {
       throw new Error(
@@ -64,8 +69,8 @@ export function createTranslationIndex<
       )
     }
 
-    // Assign directly to the entry
     group[locale] = entry
   }
+
   return Object.fromEntries(map)
 }