@soulcraft/kit-schema 2.0.0

package/src/variables.ts

@@ -0,0 +1,143 @@
+/**
+ * @module @soulcraft/kit-schema/variables
+ * @description Template variable substitution engine for Soulcraft kit files.
+ *
+ * Kit template files use `{{variableKey}}` placeholders that are replaced with
+ * the values collected during the onboarding wizard. This module provides the
+ * substitution engine used when seeding a new venue from a kit.
+ *
+ * Variable syntax: `{{key}}` — double curly braces, no spaces.
+ * Unknown variables are left as-is (no error) so that partial substitution
+ * is possible and templates can be applied incrementally.
+ *
+ * @example
+ * ```ts
+ * import { substituteVariables } from '@soulcraft/kit-schema/variables';
+ *
+ * const template = 'Welcome to {{businessName}} in {{city}}!';
+ * const result = substituteVariables(template, {
+ *   businessName: 'Wicks & Whiskers',
+ *   city: 'Charlotte'
+ * });
+ * // 'Welcome to Wicks & Whiskers in Charlotte!'
+ * ```
+ */
+
+/**
+ * Substitution context mapping variable keys to their resolved values.
+ */
+export type VariableContext = Record<string, string>;
+
+/**
+ * Replace all `{{key}}` placeholders in a template string with values from the context.
+ *
+ * Unknown keys (no matching context entry) are left as the original `{{key}}` string.
+ * This is intentional — it allows templates to be applied in stages where not all
+ * variables are known yet.
+ *
+ * @param template - The template string containing `{{key}}` placeholders.
+ * @param context - Key-value map of variable names to substitution values.
+ * @returns The template with all known `{{key}}` placeholders replaced.
+ *
+ * @example
+ * ```ts
+ * substituteVariables('Hello {{name}}!', { name: 'Alice' }); // 'Hello Alice!'
+ * substituteVariables('Hello {{name}}!', {});                 // 'Hello {{name}}!'
+ * ```
+ */
+export function substituteVariables(template: string, context: VariableContext): string {
+	return template.replace(/\{\{([^}]+)\}\}/g, (match, key: string) => {
+		const value = context[key.trim()];
+		return value !== undefined ? value : match;
+	});
+}
+
+/**
+ * Recursively substitute variables in all string values within an object or array.
+ *
+ * Traverses the entire data structure and applies {@link substituteVariables} to
+ * every string value. Non-string values (numbers, booleans, null) are left unchanged.
+ * Useful for substituting variables throughout an entire CMS content JSON file.
+ *
+ * @param data - The data structure to process (object, array, or primitive).
+ * @param context - Key-value map of variable names to substitution values.
+ * @returns A new data structure with all string values substituted.
+ *
+ * @example
+ * ```ts
+ * substituteInObject(
+ *   { title: 'Welcome to {{businessName}}', count: 5 },
+ *   { businessName: 'Wicks & Whiskers' }
+ * );
+ * // { title: 'Welcome to Wicks & Whiskers', count: 5 }
+ * ```
+ */
+export function substituteInObject(data: unknown, context: VariableContext): unknown {
+	if (typeof data === 'string') {
+		return substituteVariables(data, context);
+	}
+	if (Array.isArray(data)) {
+		return data.map((item) => substituteInObject(item, context));
+	}
+	if (data !== null && typeof data === 'object') {
+		const result: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+			result[key] = substituteInObject(value, context);
+		}
+		return result;
+	}
+	return data;
+}
+
+/**
+ * Find all `{{key}}` placeholders used in a template string.
+ *
+ * Returns a deduplicated array of variable keys found in the template.
+ * Used to validate that all required variables have been provided before
+ * substitution, and to show the user which fields they need to fill in.
+ *
+ * @param template - The template string to inspect.
+ * @returns Deduplicated array of variable key names found in the template.
+ *
+ * @example
+ * ```ts
+ * findTemplateVariables('Hello {{name}}, welcome to {{place}}!');
+ * // ['name', 'place']
+ *
+ * findTemplateVariables('No variables here');
+ * // []
+ * ```
+ */
+export function findTemplateVariables(template: string): string[] {
+	const matches = template.matchAll(/\{\{([^}]+)\}\}/g);
+	const keys = new Set<string>();
+	for (const match of matches) {
+		const key = match[1]?.trim();
+		if (key) keys.add(key);
+	}
+	return Array.from(keys);
+}
+
+/**
+ * Validate that all required variable keys from a kit's variable definitions
+ * are present in the provided context.
+ *
+ * @param requiredKeys - Array of variable keys that must be provided.
+ * @param context - The user-supplied variable context to validate.
+ * @returns Array of missing variable keys. Empty array means all required variables are present.
+ *
+ * @example
+ * ```ts
+ * validateVariableContext(
+ *   ['businessName', 'city'],
+ *   { businessName: 'Wicks & Whiskers' }
+ * );
+ * // ['city']  ← 'city' is missing
+ * ```
+ */
+export function validateVariableContext(
+	requiredKeys: string[],
+	context: VariableContext
+): string[] {
+	return requiredKeys.filter((key) => !context[key]);
+}

package/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "customConditions": ["svelte"],
+    "noEmit": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "allowImportingTsExtensions": false,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}