crelte 0.5.8 → 0.5.10

package/src/ssr/SsrCache.ts

@@ -1,4 +1,9 @@
-export async function calcKey(data: any) {
+/**
+ * Calculates a key based on the json representation of the data
+ *
+ * If available hashes the data using SHA-1
+ */
+export async function calcKey(data: any): Promise<string> {
 	const json = JSON.stringify(data);
 	// this should only happen in an unsecure context
 	// specifically in the craft preview locally
@@ -27,53 +32,130 @@ export async function calcKey(data: any) {
  * generally. Storing data and retrieving it will also work on the client.
  */
 export default class SsrCache {
-	private store: Record<string, any>;
+	private store: Map<string, any>;
 
 	constructor() {
-		this.store = {};
-
-		// @ts-ignore
-		if (typeof window !== 'undefined' && window.SSR_STORE) {
-			// @ts-ignore
-			this.store = window.SSR_STORE;
-		}
+		this.store = new Map();
 	}
 
 	/**
-	 * check if the value is in the cache else calls the fn
+	 * Check if a key exists in the cache
 	 */
-	async load<T>(key: string, fn: () => Promise<T>) {
-		if (key in this.store) return this.store[key];
-		const v = await fn();
-		this.set(key, v);
-		return v;
+	has(key: string): boolean {
+		return this.store.has(key);
 	}
 
 	/**
 	 * Get a value from the cache
 	 */
 	get<T>(key: string): T | null {
-		return this.store[key] ?? null;
+		return this.store.get(key) ?? null;
 	}
 
 	/**
 	 * Set a value in the cache
 	 */
 	set<T>(key: string, val: T): T {
-		return (this.store[key] = val);
+		this.store.set(key, val);
+		return val;
+	}
+
+	/**
+	 * check if the value is in the cache else calls the fn
+	 *
+	 * See also {@link getOrInsertLoaded}
+	 */
+	getOrInsertComputed<T>(key: string, fn: () => T): T {
+		if (this.store.has(key)) return this.store.get(key);
+		return this.set(key, fn());
+	}
+
+	/**
+	 * check if the value is in the cache else calls the fn
+	 *
+	 * See also {@link getOrInsertComputed}
+	 *
+	 * @deprecated use {@link getOrInsertLoaded} instead
+	 */
+	async load<T>(key: string, fn: () => Promise<T>): Promise<T> {
+		return this.getOrInsertLoaded<T>(key, fn);
+	}
+
+	/**
+	 * check if the value is in the cache else calls the fn
+	 *
+	 * See also {@link getOrInsertComputed}
+	 */
+	async getOrInsertLoaded<T>(key: string, fn: () => Promise<T>): Promise<T> {
+		if (this.store.has(key)) return this.store.get(key);
+		return this.set(key, await fn());
+	}
+
+	/**
+	 * One-shot SSR handoff value.
+	 *
+	 * Intended use: call this once per request (per key) during SSR to generate
+	 * a value that must match between server render and client hydration.
+	 *
+	 * On the server, the value is generated once per key and stored for hydration.
+	 * Subsequent calls with the same key during SSR currently return the same value,
+	 * but this behaviour is an implementation detail and may change in the future.
+	 * Consumers should rely on calling this at most once per key during SSR.
+	 *
+	 * On the client, the stored value is returned exactly once and removed.
+	 * Subsequent calls return a fresh value and are not cached.
+	 *
+	 * Warning: this function is designed to be called once per key during SSR.
+	 * Calling it multiple times may lead to unexpected behaviour if the server-side
+	 * implementation changes.
+	 *
+	 * See also {@link getOrInsertComputed}
+	 */
+	takeOnce<T>(key: string, fn: () => T): T {
+		if (import.meta.env.SSR) {
+			if (this.store.has(key)) {
+				console.warn(
+					`SsrCache.takeOnce called multiple times for key "${key}" during SSR.`,
+				);
+				return this.store.get(key);
+			}
+			return this.set(key, fn());
+		}
+		if (this.store.has(key)) return this.remove<T>(key)!;
+		return fn();
+	}
+
+	/**
+	 * Remove a value from the cache and return it
+	 */
+	remove<T>(key: string): T | null {
+		const val = this.get<T>(key);
+		this.store.delete(key);
+		return val;
 	}
 
 	/** @hidden */
-	clear() {
-		this.store = {};
+	z_clear() {
+		this.store.clear();
+	}
+
+	/** @hidden */
+	z_importFromHead() {
+		// @ts-ignore
+		this.store = new Map(window._SSR_STORE ?? []);
+		// @ts-ignore
+		delete window._SSR_STORE;
 	}
 
 	private exportAsJson(): string {
-		return JSON.stringify(this.store).replace(/</g, '\\u003c');
+		return JSON.stringify(Array.from(this.store.entries())).replace(
+			/</g,
+			'\\u003c',
+		);
 	}
 
 	/** @hidden */
-	exportToHead(): string {
-		return `\n\t\t<script>window.SSR_STORE = ${this.exportAsJson()};</script>`;
+	z_exportToHead(): string {
+		return `\n\t\t<script>window._SSR_STORE = ${this.exportAsJson()};</script>`;
 	}
 }

package/src/std/index.ts

@@ -1,3 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * Crelte Standard library
+ *
+ * Provides standard utility functions and types for Crelte applications.
+ *
+ * ### Modules:
+ * - {@link std/intl}
+ * - {@link std/stores}
+ * - {@link std/sync}
+ * - {@link std/rand}
+ */
+
 /**
  * Delays for a specified amount of time.
  *

package/src/std/rand/index.ts

@@ -0,0 +1,55 @@
+import { Crelte } from '../../crelte.js';
+import { getCrelte } from '../../index.js';
+
+/**
+ * Returns a random number between 0 (inclusive) and 1 (exclusive).
+ *
+ * In SSR mode, the same key will always return the same random number.
+ * In client mode, the first call will return the number generated during SSR.
+ */
+export function random(key: string, crelte: Crelte = getCrelte()): number {
+	return crelte.ssrCache.takeOnce('_rand_' + key, () => Math.random());
+}
+
+/**
+ * Create a deterministic random number generator.
+ *
+ * Intended use: create this once during component initialization when a sequence
+ * of random values must be consistent between server-side rendering and client
+ * hydration.
+ *
+ * The generator is seeded during SSR using the provided key. During hydration,
+ * the same seed is reused so that the client produces the same sequence of random
+ * numbers as the server for the initial render.
+ *
+ * After hydration, the generator continues independently on the client.
+ *
+ * @returns A function that returns a pseudo-random number in the range
+ *          [0, 1).
+ *
+ * #### Example
+ * ```ts
+ * const rng = createRng('lucky-number');
+ *
+ * const val1 = rng(); // same on server and client
+ * const val2 = rng(); // same on server and client
+ * ```
+ */
+export function createRng(
+	key: string,
+	crelte: Crelte = getCrelte(),
+): () => number {
+	const seed = crelte.ssrCache.takeOnce('_rng_' + key, () => Math.random());
+
+	// park miller algorithm
+
+	const MOD = 2147483647;
+	const MUL = 16807;
+
+	let state = Math.floor(seed * (MOD - 1)) + 1;
+
+	return () => {
+		state = (state * MUL) % MOD;
+		return (state - 1) / (MOD - 1);
+	};
+}

package/src/std/rand/internal.ts

@@ -0,0 +1,17 @@
+const ALPHABET: string =
+	'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+const ALPHABET_LENGTH = ALPHABET.length;
+
+/**
+ * Generates a random token of a specified length.
+ *
+ * @param length - The desired length of the token.
+ * @returns A random token.
+ */
+export function randomToken(length: number = 8): string {
+	let s = '';
+	for (let i = 0; i < length; i++) {
+		s += ALPHABET[Math.floor(Math.random() * ALPHABET_LENGTH)];
+	}
+	return s;
+}

package/src/std/stores/Writable.ts

@@ -27,7 +27,7 @@ export default class Writable<T> {
 	 * The function get's called once with the current value and then when the
 	 * values changes
 	 *
-	 * ## Note
+	 * #### Note
 	 * This does not check for equality like svelte.
 	 *
 	 * @return a function which should be called to unsubscribe

package/src/translations/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @packageDocumentation
+ *
+ * ## Unstable
+ * The translations module is not yet stable. APIs may change without a major version bump.
+ */
+
+import { createFileLoader } from './loader/fileLoader/fileLoader.js';
+import { createGlobalLoader } from './loader/GlobalLoader.js';
+import { type TranslationsLoader, type LoaderCreator } from './loader/index.js';
+import loadTranslations from './loadTranslations.js';
+import {
+	createTranslations,
+	getTranslationsPlugin,
+	type TranslateFunction,
+	type TranslateStore,
+	type Translations,
+	TranslationsPlugin,
+	type TranslationsPluginOptions,
+} from './translationsPlugin.js';
+
+/**
+ * Creates a translate store for the given namespace.
+ *
+ * #### Example
+ * ```svelte
+ * <script>
+ * 	import { getTranslations } from 'crelte/translations';
+ *
+ * 	const t = getTranslations();
+ * </script>
+ *
+ * <h1>{$t('welcome_message')}</h1>
+ * ```
+ */
+function getTranslations(namespace: string = 'common'): TranslateStore {
+	const plugin = getTranslationsPlugin();
+	return plugin.z_createTranslateStore(namespace);
+}
+
+export {
+	createTranslations,
+	TranslationsPluginOptions,
+	loadTranslations,
+	getTranslations,
+	getTranslationsPlugin,
+	Translations,
+	TranslationsPlugin,
+	TranslationsLoader,
+	LoaderCreator,
+	TranslateStore,
+	TranslateFunction,
+	// loaders
+	createFileLoader,
+	createGlobalLoader,
+};

package/src/translations/loadTranslations.ts

@@ -0,0 +1,33 @@
+import { CrelteRequest } from '../crelte.js';
+import { getTranslationsPlugin, TranslateStore } from './translationsPlugin.js';
+
+/**
+ * Creates a translate store and loads the specified namespace.
+ *
+ * #### Example
+ * ```svelte
+ * <script module>
+ * 	import { loadTranslations } from 'crelte/translations';
+ * 	export const loadData = {
+ * 		t: cr => loadTranslations(cr, 'customNamespace')
+ * 	};
+ * </script>
+ *
+ * <script>
+ * 	let { t } = $props();
+ * </script>
+ *
+ * <h1>{$t('welcome_message')}</h1>
+ * ```
+ */
+export default async function loadTranslations(
+	cr: CrelteRequest,
+	namespace: string,
+): Promise<TranslateStore> {
+	const plugin = getTranslationsPlugin(cr);
+
+	// we don't need the return value here as it's cached
+	await plugin.load(cr, namespace);
+
+	return plugin.z_createTranslateStore(namespace);
+}

package/src/translations/loader/GlobalLoader.ts

@@ -0,0 +1,62 @@
+import { Translations } from '../translationsPlugin.js';
+import { Crelte, CrelteRequest } from '../../crelte.js';
+import { LoaderCreator, TranslationsLoader } from '../index.js';
+
+export default class GlobalLoader implements TranslationsLoader {
+	private handle: string;
+
+	constructor(_crelte: Crelte, opts: { handle?: string }) {
+		this.handle = opts.handle ?? 'translations';
+	}
+
+	async load(cr: CrelteRequest, namespace: string): Promise<Translations> {
+		const globalSet = await cr.globals.getAsync(this.handle);
+		if (!globalSet || typeof globalSet !== 'object')
+			throw new Error(`missing globals \`${this.handle}\``);
+
+		const data = globalSet[namespace];
+		if (!data)
+			throw new Error(
+				`could not find \`${namespace}\` in globals \`${this.handle}\``,
+			);
+
+		if (typeof data !== 'string') return data;
+
+		try {
+			return JSON.parse(data);
+		} catch (e) {
+			throw new Error(
+				`could not parse \`${this.handle}.${namespace}\` as json \n\n` +
+					(e instanceof Error ? e.message : ''),
+			);
+		}
+	}
+}
+
+/**
+ * Creates a loader that loads translations from a global set.
+ *
+ * ```ts
+ * import { createTranslations, createGlobalLoader } from 'crelte/translations';
+ *
+ * createTranslations({ loader: createGlobalLoader() });
+ * ```
+ *
+ * Then in you're global export a `translations` globalSet with namespaces
+ * as fields, at least `common`.
+ *
+ * ```graphql
+ * translations: globalSet(handle: "translations", siteId: $siteId) {
+ *   ... on translations_GlobalSet {
+ *     common
+ *   }
+ * }
+ */
+export function createGlobalLoader(
+	opts: {
+		/** the handle for the global set containing the namespaces (default = translations) */
+		handle?: string;
+	} = {},
+): LoaderCreator {
+	return crelte => new GlobalLoader(crelte, opts);
+}

package/src/translations/loader/fileLoader/ClientFileLoader.ts

@@ -0,0 +1,40 @@
+import { CrelteRequest } from '../../../crelte.js';
+import SsrCache from '../../../ssr/SsrCache.js';
+import { Translations } from '../../translationsPlugin.js';
+import { TranslationsLoader } from '../index.js';
+import { SSR_RUN_NUMBER_KEY, translationFilePath } from './fileLoader.js';
+
+export default class ClientFileLoader implements TranslationsLoader {
+	private readonly runNumber: string;
+
+	constructor(cache: SsrCache) {
+		this.runNumber = cache.get(SSR_RUN_NUMBER_KEY) ?? '';
+	}
+
+	async load(cr: CrelteRequest, namespace: string): Promise<Translations> {
+		const lang = cr.site.language;
+
+		try {
+			const resp = await fetch(
+				`${translationFilePath(lang, namespace)}?run=${this.runNumber}`,
+			);
+
+			if (!resp.ok) {
+				throw new Error(
+					`Failed to fetch translations file for ${lang}/${namespace}`,
+				);
+			}
+
+			// todo: validate data
+			const data: Translations = await resp.json();
+
+			return data;
+		} catch (e: unknown) {
+			console.error(e);
+			throw new Error(
+				'There is something wrong with your translations file. \n\n' +
+					(e instanceof Error ? e.message : ''),
+			);
+		}
+	}
+}

package/src/translations/loader/fileLoader/NodeFileLoader.ts

@@ -0,0 +1,32 @@
+import fs from 'node:fs/promises';
+import { SSR_RUN_NUMBER_KEY, translationFilePath } from './fileLoader.js';
+import { randomToken } from '../../utils.js';
+import { Translations } from '../../translationsPlugin.js';
+import SsrCache from '../../../ssr/SsrCache.js';
+import { CrelteRequest } from '../../../crelte.js';
+import { TranslationsLoader } from '../index.js';
+
+export default class NodeFileLoader implements TranslationsLoader {
+	constructor(cache: SsrCache) {
+		// store RUN_NUMBER in ssr store
+		cache.set(SSR_RUN_NUMBER_KEY, randomToken());
+	}
+
+	async load(cr: CrelteRequest, namespace: string): Promise<Translations> {
+		const lang = cr.site.language;
+
+		try {
+			const fileString = await fs.readFile(
+				`./public${translationFilePath(lang, namespace)}`,
+				'utf-8',
+			);
+			// todo: validate data
+			return JSON.parse(fileString) as Translations;
+		} catch (e: unknown) {
+			throw new Error(
+				'There is something wrong with your translations file. \n\n' +
+					(e instanceof Error ? e.message : ''),
+			);
+		}
+	}
+}

package/src/translations/loader/fileLoader/fileLoader.ts

@@ -0,0 +1,19 @@
+import { LoaderCreator } from '../index.js';
+import ClientFileLoader from './ClientFileLoader.js';
+import NodeFileLoader from './NodeFileLoader.js';
+
+export const SSR_RUN_NUMBER_KEY = 'st-run-number';
+
+/// Returns a path to the translations file for the given language and namespace.
+/// Always prefixed with a slash.
+export function translationFilePath(lang: string, namespace: string): string {
+	return `/translations/${lang}/${namespace}.json`;
+}
+
+export function createFileLoader(): LoaderCreator {
+	if (import.meta.env.SSR) {
+		return crelte => new NodeFileLoader(crelte.ssrCache);
+	} else {
+		return crelte => new ClientFileLoader(crelte.ssrCache);
+	}
+}

package/src/translations/loader/index.ts

@@ -0,0 +1,8 @@
+import { Translations } from '../translationsPlugin.js';
+import { Crelte, CrelteRequest } from '../../crelte.js';
+
+export interface TranslationsLoader {
+	load(cr: CrelteRequest, namespace: string): Promise<Translations>;
+}
+
+export type LoaderCreator = (crelte: Crelte) => TranslationsLoader;

package/src/translations/translationsPlugin.ts

@@ -0,0 +1,145 @@
+import { derived } from 'svelte/store';
+import { LoaderCreator, TranslationsLoader } from './loader/index.js';
+import { Plugin, PluginCreator } from '../plugins/Plugins.js';
+import { Crelte, CrelteRequest } from '../crelte.js';
+import Readable from '../std/stores/Readable.js';
+import { getCrelte } from '../index.js';
+
+export type TranslateFunction = (
+	key: string,
+	// replacements?: Record<string, string>,
+) => string;
+export type TranslateStore = Readable<TranslateFunction>;
+export type Translations = Record<string, string>;
+export type TranslationsPluginOptions = {
+	/** use either `createFileLoader()` or `createGlobalLoader()` */
+	loader: LoaderCreator;
+	/** The common namespace is always loaded  */
+	loadNamespaces?: string[];
+};
+
+const SSR_KEY = '_translations';
+
+export class TranslationsPlugin implements Plugin {
+	private crelte: Crelte;
+	/// Map<`lang-namespace`, Translations>
+	private translations: Map<string, Translations>;
+	private loader: TranslationsLoader;
+	/// When the derived of site is used in the first loadData site is not defined
+	/// so we need to store the first language here
+	private firstLang: string | null;
+
+	get name(): string {
+		return 'translations';
+	}
+
+	constructor(crelte: Crelte, opts: TranslationsPluginOptions) {
+		this.crelte = crelte;
+		this.translations = new Map(crelte.ssrCache.get(SSR_KEY));
+		this.firstLang = null;
+
+		if (import.meta.env.DEV && typeof opts?.loader !== 'function') {
+			throw new Error(
+				'TranslationsPlugin requires a loader, use `createFileLoader()` or ' +
+					'`createGlobalLoader()`',
+			);
+		}
+
+		this.loader = opts.loader(crelte);
+		const loadNamespaces = opts.loadNamespaces ?? [];
+
+		// preload default translations
+		crelte.events.on('loadGlobalData', async (cr: CrelteRequest) => {
+			this.firstLang = cr.site.language;
+			await Promise.all([
+				this.load(cr, 'common'),
+				...loadNamespaces.map(ns => this.load(cr, ns)),
+			]);
+		});
+	}
+
+	/**
+	 * load needs to take a CrelteRequest to be able to get the correct site
+	 * and globals
+	 *
+	 * in crelte 0.5 this should also be possible without a CrelteRequest
+	 * but with multiple plugin instances / Request State plugins
+	 */
+	async load(cr: CrelteRequest, namespace: string): Promise<Translations> {
+		const lang = cr.site.language;
+		const key = `${lang}-${namespace}`;
+		const tData = this.translations.get(key);
+		if (tData) return tData;
+
+		const data = await this.loader.load(cr, namespace);
+		this.translations.set(key, data);
+		if (import.meta.env.SSR) {
+			// only store the translations in the ssrCache during ssr
+			// since after that we wont read it again
+			cr.ssrCache.set(SSR_KEY, Array.from(this.translations.entries()));
+		}
+
+		return data;
+	}
+
+	get(lang: string, namespace: string): Translations | null {
+		return this.translations.get(`${lang}-${namespace}`) ?? null;
+	}
+
+	/** @hidden */
+	z_createTranslateStore(namespace: string): TranslateStore {
+		const store = derived(this.crelte.router.site, site => {
+			return (key: string) => {
+				const lang = site?.language ?? this.firstLang;
+				if (!lang) throw new Error('no lang');
+
+				const data = this.get(lang, namespace);
+				if (!data) console.error(`namespace '${namespace}' not loaded`);
+				return data?.[key] || key;
+			};
+		});
+
+		return new Readable(store);
+	}
+}
+
+/**
+ * Create the TranslationsPlugin
+ *
+ * #### Setup file loader
+ *
+ * ```ts
+ * import { createTranslations, createFileLoader } from 'crelte/translations';
+ *
+ * createTranslations({ loader: createFileLoader() });
+ * ```
+ *
+ * #### Setup global loader
+ * ```ts
+ * import { createTranslations, createGlobalLoader } from 'crelte/translations';
+ *
+ * createTranslations({ loader: createGlobalLoader() });
+ * ```
+ *
+ * Then in you're global export a `translations` globalSet with namespaces
+ * as fields, at least `common`.
+ *
+ * ```graphql
+ * translations: globalSet(handle: "translations", siteId: $siteId) {
+ *   ... on translations_GlobalSet {
+ *     common
+ *   }
+ * }
+ * ```
+ */
+export function createTranslations(
+	opts: TranslationsPluginOptions,
+): PluginCreator {
+	return crelte => new TranslationsPlugin(crelte, opts);
+}
+
+export function getTranslationsPlugin(
+	crelte: Crelte = getCrelte(),
+): TranslationsPlugin {
+	return crelte.getPlugin('translations') as TranslationsPlugin;
+}

package/src/translations/utils.ts

@@ -0,0 +1,17 @@
+const ALPHABET: string =
+	'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+const ALPHABET_LENGTH = ALPHABET.length;
+
+/**
+ * Generates a random token of a specified length.
+ *
+ * @param length - The desired length of the token.
+ * @returns A random token.
+ */
+export function randomToken(length: number = 8): string {
+	let s = '';
+	for (let i = 0; i < length; i++) {
+		s += ALPHABET[Math.floor(Math.random() * ALPHABET_LENGTH)];
+	}
+	return s;
+}