@enonic-types/global 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# Enonic XP global TS types
+
+> TypeScript definitions for global variables of Enonic XP
+
+## Install
+
+```bash
+npm i --save-dev @enonic-types/global
+```
+
+## Use
+
+Add the corresponding types to your `tsconfig.json` file that is used for application's server-side TypeScript code:
+
+```json
+{
+  "compilerOptions": {
+    "typeRoots": [
+      "node_modules/@types",
+      "node_modules/@enonic-types",
+    ]
+  }
+}
+```
+
+> The paths to the `node_mosules` assume that your `tsconfig.json` is placed under your project root.
+
+After that, all the global XP variables will be typed.
+
+Adding not `"types": [...]` but `"typeRoots"` will allow to discover types for every other enonic library, that will be installed later.
+
+Import functions, such as `require`, will return typed objects if the corresponding types for imported
+libraries are also added to your `tsconfig.json`.
+
+## Configuration
+
+### Require
+
+To add support for type resolution for the custom libraries via `require`, you can redeclare the `XpLibraries` interface in global scope, wich will lead to declaration merging:
+
+```ts
+declare global {
+    interface XpLibraries {
+        '/lib/custom/mylib': typeof import('./mylib');
+    }
+}
+```
+
+__Other imports__
+
+If you want to use custom import functions, like `__non_webpack_require__` with Webpack, just use global `XpRequire` type for this:
+```ts
+declare const __non_webpack_require__: XpRequire;
+```
+
+### Beans
+
+To create a new bean, a `__.newBean()` function must be used. Making it return a proper type can be done in two ways. Say you have create an interface for that been somewhere in your project:
+
+```ts
+interface SomeHelper {
+  help(text: string): void;
+}
+```
+
+__Option 1__
+
+You can pass the type argument explicitly. This option is a bit cleaner.
+
+```ts
+const helper = __.newBean<SomeHelper>('com.me.project.SomeHelper');
+```
+
+__Option 2__
+
+Or you can map the bean name to bean interface. It may be a preferable way to do it, if the bean is used across multiple files:
+
+```ts
+declare global {
+    interface XpBeans {
+        'com.me.project.SomeHelper': SomeHelper;
+    }
+}
+
+const helper = __.newBean('com.me.project.SomeHelper');
+```

package/global.d.ts

@@ -0,0 +1,18 @@
+/**
+ * This project don't include XP libraries definitions and need this interface
+ * to properly map imports via require.
+ *
+ * Warning: this interface is empty. If you want type definitions for various
+ * libraries, you need to redefine this interface in your library in global
+ * path and add a new property with library path.
+ *
+ * @example
+ * declare global {
+ *     interface XpLibraries {
+ *         '/lib/xp/event': typeof import('./event');
+ *     }
+ * }
+*/
+interface XpLibraries {}
+
+interface XpBeans {}

package/index.d.ts

@@ -0,0 +1,54 @@
+/// <reference path='global.d.ts' />
+
+declare const app: {
+    name: string;
+    version: string;
+    config: Record<string, string | undefined>;
+};
+
+declare const log: {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warning: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+
+declare interface ScriptValue {
+    isArray(): boolean;
+
+    isObject(): boolean;
+
+    isValue(): boolean;
+
+    isFunction(): boolean;
+
+    getValue(): unknown;
+
+    getKeys(): string[];
+
+    hasMember(key: string): boolean;
+
+    getMember(key: string): ScriptValue;
+
+    getArray(): ScriptValue[];
+
+    getMap(): Record<String, unknown>;
+
+    getList(): object[];
+}
+
+type NewBean = <T = unknown, Bean extends keyof XpBeans | string = string>(bean: Bean) =>
+    Bean extends keyof XpBeans ? XpBeans[Bean] : T;
+
+declare const __: {
+    newBean: NewBean;
+    toNativeObject: <T = unknown>(beanResult: T) => T;
+    toScriptValue: <T = object>(value: T) => ScriptValue;
+    disposer: (callback: (...args: unknown[]) => unknown) => void;
+    nullOrValue: <T = object>(value: T) => T | null | undefined;
+};
+
+declare type XpRequire = <Key extends keyof XpLibraries | string = string>(path: Key) =>
+    Key extends keyof XpLibraries ? XpLibraries[Key] : unknown;
+
+declare const require: XpRequire;

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@enonic-types/global",
+    "version": "0.1.0",
+    "description": "Type definitions for XP JavaScript global object properties.",
+    "types": "index.d.ts",
+    "files": [
+        "index.d.ts",
+        "global.d.ts"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/enonic/xp.git#master"
+    },
+    "keywords": [
+        "enonic",
+        "enonic-xp",
+        "global",
+        "types",
+        "typescript"
+    ],
+    "contributors": [
+        "Mikita Taukachou <edloidas@gmail.com> (https://edloidas.github.io/)"
+    ],
+    "license": "Apache-2.0",
+    "bugs": {
+        "url": "https://github.com/enonic/xp/issues"
+    },
+    "homepage": "https://github.com/enonic/xp/tree/master#readme",
+    "publishConfig": {
+        "access": "public"
+    }
+}