@aidc-toolkit/core 0.0.1

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,32 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/.idea/core.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,7 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="UpdateDependencyToLatestVersion" enabled="true" level="WARNING" enabled_by_default="true" editorAttributes="WARNING_ATTRIBUTES" />
+  </profile>
+</component>

package/.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="openjdk-21" project-jdk-type="JavaSDK">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/core.iml" filepath="$PROJECT_DIR$/.idea/core.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/runConfigurations/build.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="build" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="build" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/.idea/runConfigurations/eslint.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="eslint" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="eslint" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/README.md

@@ -0,0 +1,38 @@
+The AIDC Toolkit `core` package contains artefacts to support other AIDC Toolkit packages; it does not itself provide
+any of the functionality of the AIDC Toolkit. It is a required dependency for all AIDC Toolkit packages.
+
+## Localization
+
+All AIDC Toolkit packages require localization. The localization functionality in this package simplifies initialization
+and allows packages to share a common internationalization engine, whose initialization is the responsibility of the
+client application. Packages install their resources as follows in `i18n.ts` or similar:
+
+```typescript
+import { i18nAddResourceBundle, i18next } from "@aidc-toolkit/core";
+import { localeStrings as enLocaleStrings } from "./en/locale_strings.js";
+
+export const packageNS = "aidct_package";
+
+i18nAddResourceBundle("en", packageNS, enLocaleStrings);
+
+export default i18next;
+```
+
+The resource types are declared in `i18next.d.ts` or similar:
+
+```typescript
+import type { localeStrings } from "./en/locale_strings.js";
+
+declare module "i18next" {
+    interface CustomTypeOptions {
+        resources: {
+            // Extract the type from the English locale strings object.
+            aidct_package: typeof localeStrings;
+        };
+    }
+}
+```
+
+## Resources
+
+The `resource` folder contains common resources (e.g., AIDC Toolkit icon) usable by all AIDC Toolkit packages.

package/eslint.config.js

@@ -0,0 +1,15 @@
+import tseslint from "typescript-eslint";
+import js from "@eslint/js";
+import stylistic from "@stylistic/eslint-plugin";
+import jsdoc from "eslint-plugin-jsdoc";
+import esLintConfigLove from "eslint-config-love";
+import { esLintConfigAIDCToolkit } from "@aidc-toolkit/dev";
+
+export default tseslint.config(
+    js.configs.recommended,
+    ...tseslint.configs.strictTypeChecked,
+    stylistic.configs["recommended-flat"],
+    jsdoc.configs["flat/recommended-typescript"],
+    esLintConfigLove,
+    esLintConfigAIDCToolkit
+);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@aidc-toolkit/core",
+  "version": "0.0.1",
+  "description": "Core functionality for AIDC Toolkit",
+  "type": "module",
+  "main": "dist/index.js",
+  "homepage": "https://github.com/aidc-toolkit",
+  "repository": "github:aidc-toolkit/core",
+  "bugs": {
+    "url": "https://github.com/aidc-toolkit/core/issues"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Kevin Dean",
+    "email": "Kevin.Dean@datadevelopment.com",
+    "url": "https://www.linkedin.com/in/kdean"
+  },
+  "scripts": {
+    "eslint": "eslint .",
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@aidc-toolkit/dev": "^0.0.1",
+    "@eslint/js": "^9.10.0",
+    "@stylistic/eslint-plugin": "^2.7.2",
+    "eslint-config-love": "^64.0.0",
+    "eslint-plugin-jsdoc": "^50.2.2",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.4.0",
+    "vitest": "^2.0.5"
+  },
+  "dependencies": {
+    "i18next": "^23.14.0",
+    "i18next-browser-languagedetector": "^8.0.0",
+    "i18next-cli-language-detector": "^1.1.8"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./locale/i18n.js";
+export { default as i18next } from "./locale/i18n.js";

package/src/locale/i18n.ts

@@ -0,0 +1,110 @@
+import i18next from "i18next";
+import I18nextBrowserLanguageDetector from "i18next-browser-languageDetector";
+import I18nextCLILanguageDetector from "i18next-cli-language-detector";
+
+export default i18next;
+
+/**
+ * Internal type to maintain resource bundles added before initialization.
+ */
+interface ResourceBundle {
+    lng: string;
+    ns: string;
+    resources: object;
+}
+
+/**
+ * Internal array to maintain resource bundles added before initialization.
+ */
+let pendingResourceBundles: ResourceBundle[] | undefined = [];
+
+/**
+ * Internationalization operating environment.
+ */
+export enum I18NEnvironment {
+    /**
+     * Command-line interface (e.g., unit tests).
+     */
+    CLI,
+
+    /**
+     * Web server.
+     */
+    Server,
+
+    /**
+     * Web browser.
+     */
+    Browser
+}
+
+/**
+ * Initialize internationalization.
+ *
+ * @param environment
+ * Environment in which the application is running.
+ *
+ * @param debug
+ * Debug setting.
+ */
+export async function i18nInit(environment: I18NEnvironment, debug = false): Promise<void> {
+    if (pendingResourceBundles !== undefined) {
+        let module: object;
+
+        switch (environment) {
+            case I18NEnvironment.CLI:
+                module = I18nextCLILanguageDetector;
+                break;
+
+            case I18NEnvironment.Browser:
+                module = I18nextBrowserLanguageDetector;
+                break;
+
+            default:
+                throw new Error("Not supported");
+        }
+
+        await i18next.use(module as never).init({
+            fallbackLng: "en",
+            debug,
+            resources: {}
+        }).then(() => {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const initResourceBundles = pendingResourceBundles!;
+
+            // No need to manage pending resource bundles past this point.
+            pendingResourceBundles = undefined;
+
+            // Add pending resource bundles.
+            initResourceBundles.forEach((initResourceBundle) => {
+                i18nAddResourceBundle(initResourceBundle.lng, initResourceBundle.ns, initResourceBundle.resources);
+            });
+        });
+    } else {
+        throw new Error("i18n already initialized");
+    }
+}
+
+/**
+ * Add a resource bundle.
+ *
+ * @param lng
+ * Language.
+ *
+ * @param ns
+ * Namespace.
+ *
+ * @param resources
+ * Resources.
+ */
+export function i18nAddResourceBundle(lng: string, ns: string, resources: object): void {
+    if (pendingResourceBundles !== undefined) {
+        pendingResourceBundles.push({
+            lng,
+            ns,
+            resources
+        });
+    } else {
+        i18next.addResourceBundle(lng, ns, resources);
+    }
+}

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@aidc-toolkit/dev/tsconfig.json"
+}

package/typedoc.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "extends": [
+    "@aidc-toolkit/dev/typedoc.json"
+  ],
+  "name": "Core",
+  "entryPoints": [
+    "src/index.ts"
+  ]
+}