refactor: rewrite runtime-core in TypeScript with intermediate build step

Author: joshunrau

.gitignore

@@ -62,3 +62,6 @@ apps/outreach/src/content/docs/en/runtime-core-docs/
 # docker dbs
 mongo/
 sqlite/
+
+# runtime core intermediate build
+packages/runtime-core/lib/

packages/runtime-core/config/api-extractor.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  "mainEntryPointFilePath": "<projectFolder>/src/index.d.ts",
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
   "bundledPackages": ["@douglasneuroinformatics/libui-form-types"],
   "apiReport": {
     "enabled": false

packages/runtime-core/package.json

@@ -12,9 +12,9 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "rm -rf dist && pnpm build:js && pnpm build:ts",
-    "build:js": "pnpm exec esbuild --bundle --format=esm --outfile=dist/index.js --platform=browser src/index.js",
-    "build:ts": "api-extractor run -c config/api-extractor.json",
+    "build": "rm -rf dist lib && pnpm build:lib && pnpm build:dist",
+    "build:dist": "pnpm exec esbuild --bundle --format=esm --outfile=dist/index.js --platform=browser lib/index.js && api-extractor run -c config/api-extractor.json",
+    "build:lib": "tsc -b tsconfig.build.json",
     "format": "prettier --write src",
     "lint": "tsc --noEmit && eslint --fix src"
   },

packages/runtime-core/src/__tests__/define.test-d.ts

@@ -3,9 +3,9 @@ import { z } from 'zod';
 
 import { defineInstrument } from '../define.js';
 
-import type { DiscriminatedInstrument } from '../define.d.ts';
-import type { FormInstrument } from '../types/instrument.form.d.ts';
-import type { InteractiveInstrument } from '../types/instrument.interactive.d.ts';
+import type { DiscriminatedInstrument } from '../define.js';
+import type { FormInstrument } from '../types/instrument.form.js';
+import type { InteractiveInstrument } from '../types/instrument.interactive.js';
 
 expectTypeOf<DiscriminatedInstrument<'FORM', 'en', { foo: string }>>().toMatchTypeOf<
   FormInstrument<{ foo: string }, 'en'>

packages/runtime-core/src/define.js

@@ -1,12 +1,12 @@
 import type { z } from 'zod';
 
-import type { InstrumentKind, InstrumentLanguage } from './types/instrument.base.d.ts';
-import type { FormInstrument } from './types/instrument.form.d.ts';
-import type { InteractiveInstrument } from './types/instrument.interactive.d.ts';
+import type { InstrumentKind, InstrumentLanguage } from './types/instrument.base.js';
+import type { FormInstrument } from './types/instrument.form.js';
+import type { InteractiveInstrument } from './types/instrument.interactive.js';
 
 /** @public */
 // prettier-ignore
-type DiscriminatedInstrument<
+export type DiscriminatedInstrument<
   TKind extends InstrumentKind,
   TLanguage extends InstrumentLanguage,
   TData
@@ -21,7 +21,7 @@ type DiscriminatedInstrument<
     : never;
 
 /** @public */
-type InstrumentDef<
+export type InstrumentDef<
   TKind extends InstrumentKind,
   TLanguage extends InstrumentLanguage,
   TSchema extends z.ZodTypeAny
@@ -35,8 +35,12 @@ type InstrumentDef<
 };
 
 /** @public */
-export declare function defineInstrument<
+export function defineInstrument<
   TKind extends InstrumentKind,
   TLanguage extends InstrumentLanguage,
   TSchema extends z.ZodTypeAny
->(def: InstrumentDef<TKind, TLanguage, TSchema>): DiscriminatedInstrument<TKind, TLanguage, z.TypeOf<TSchema>>;
+>(def: InstrumentDef<TKind, TLanguage, TSchema>) {
+  return Object.assign(def, {
+    __runtimeVersion: 1
+  }) as unknown as DiscriminatedInstrument<TKind, TLanguage, z.TypeOf<TSchema>>;
+}

packages/runtime-core/src/define.d.ts packages/runtime-core/src/define.tspackages/runtime-core/src/define.d.ts renamed to packages/runtime-core/src/define.ts

@@ -1,24 +1,29 @@
 import { get } from 'lodash-es';
 
-import type { Language } from './types/core.d.ts';
+import type { Language } from './types/core.js';
 
-type LanguageChangeHandler = (this: void, language: Language) => void;
+/** @alpha */
+export type LanguageChangeHandler = (this: void, language: Language) => void;
 
-type TranslationKey<T extends { [key: string]: unknown }, Key = keyof T> = Key extends string
+/** @alpha */
+export type TranslationKey<T extends { [key: string]: unknown }, Key = keyof T> = Key extends string
   ? T[Key] extends { [key: string]: unknown }
     ? T[Key] extends { [K in Language]: string }
       ? Key
       : `${Key}.${TranslationKey<T[Key]>}`
     : `${Key}`
   : never;
 
-type I18N<T extends { [key: string]: unknown }> = {
+/** @alpha */
+export type I18N<T extends { [key: string]: unknown }> = {
+  changeLanguage: (language: Language) => void;
   readonly resolvedLanguage: Language;
   set onLanguageChange(value: LanguageChangeHandler);
   readonly t: (key: TranslationKey<T>) => string;
 };
 
-export function createInstance<const T extends { [key: string]: unknown }>({
+/** @alpha */
+export function createI18Next<const T extends { [key: string]: unknown }>({
   fallbackLanguage = 'en',
   translations
 }: {
@@ -28,8 +33,12 @@ export function createInstance<const T extends { [key: string]: unknown }>({
   let resolvedLanguage: Language;
   let handleLanguageChange: LanguageChangeHandler | null = null;
 
+  if (!window) {
+    throw new Error('Window is not defined');
+  }
+
   const documentElement = window.top!.document.documentElement;
-  const extractLanguageProperty = (element: HTMLElement): Language => {
+  const extractLanguageProperty = (element: HTMLElement) => {
     if (element.lang === 'en' || element.lang === 'fr') {
       return element.lang;
     }
@@ -51,16 +60,21 @@ export function createInstance<const T extends { [key: string]: unknown }>({
   languageAttributeObserver.observe(documentElement, { attributes: true });
 
   return {
+    changeLanguage: (language) => {
+      window.top!.document.dispatchEvent(new CustomEvent('changeLanguage', { detail: language }));
+    },
     set onLanguageChange(handler: LanguageChangeHandler) {
       handleLanguageChange = handler;
     },
-    resolvedLanguage,
+    get resolvedLanguage() {
+      return resolvedLanguage;
+    },
     t: (key) => {
-      const value = get(translations, key) as { [K in Language]?: string } | string;
+      const value = get(translations, key) as { [key: string]: string } | string | undefined;
       if (typeof value === 'string') {
         return value;
       }
-      return value[resolvedLanguage] ?? value[fallbackLanguage] ?? key;
+      return value?.[resolvedLanguage] ?? value?.[fallbackLanguage] ?? key;
     }
   };
 }