@enonic-types/global 0.1.1 → 7.11.0-B2

package/README.md

@@ -17,7 +17,7 @@ Add the corresponding types to your `tsconfig.json` file that is used for applic
   "compilerOptions": {
     "typeRoots": [
       "node_modules/@types",
-      "node_modules/@enonic-types",
+      "node_modules/@enonic-types"
     ]
   }
 }
@@ -29,8 +29,8 @@ 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`.
+Import functions, such as `require`, will return typed objects if the corresponding types for imported libraries are also added to
+your `tsconfig.json`.
 
 ## Configuration
 
@@ -47,24 +47,26 @@ declare global {
 }
 ```
 
-__Other imports__
+#### 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:
+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 created
+an interface for that been somewhere in your project:
 
 ```ts
 interface SomeHelper {
-  help(text: string): void;
+    help(text: string): void;
 }
 ```
 
-__Option 1__
+#### Option 1
 
 You can pass the type argument explicitly. This option is a bit cleaner.
 
@@ -72,7 +74,7 @@ You can pass the type argument explicitly. This option is a bit cleaner.
 const helper = __.newBean<SomeHelper>('com.me.project.SomeHelper');
 ```
 
-__Option 2__
+#### 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:
 

package/global.d.ts

@@ -2,16 +2,86 @@ interface XpLibraries {}
 
 interface XpBeans {}
 
+/**
+ * The globally available app object holds information about the contextual application.
+ * @example
+ * var nameVersion = app.name + ' v' + app.version;
+ *
+ * @global
+ * @namespace
+ */
 declare const app: {
+    /**
+     * The name of the application.
+     *
+     * @type string
+     */
     name: string;
+    /**
+     * Version of the application.
+     *
+     * @type string
+     */
     version: string;
+    /**
+     * Values from the application’s configuration file.
+     * This can be set using $XP_HOME/config/<app.name>.cfg.
+     * Every time the configuration is changed the app is restarted.
+     *
+     * @type Object
+     */
     config: Record<string, string | undefined>;
 };
 
+/**
+ * Logging functions.
+ *
+ * @example
+ * // Log with simple message
+ * log.debug('My log message');
+ *
+ * @example
+ * // Log with placeholders
+ * log.info('My %s message with %s', 'log', 'placeholders');
+ *
+ * @example
+ * // Log a JSON object
+ * log.warning('My JSON: %s', {a: 1});
+ *
+ * @example
+ * // Log JSON object using string
+ * log.error('My JSON: %s', JSON.stringify({a: 1}, null, 2));
+ *
+ * @global
+ * @namespace
+ */
 declare const log: {
+    /**
+     * Log debug message.
+     *
+     * @param {Array} args... logging arguments.
+     */
     debug: (...args: unknown[]) => void;
+
+    /**
+     * Log info message.
+     *
+     * @param {Array} args... logging arguments.
+     */
     info: (...args: unknown[]) => void;
+
+    /**
+     * Log warning message.
+     *
+     * @param {Array} args... logging arguments.
+     */
     warning: (...args: unknown[]) => void;
+
+    /**
+     * Log error message.
+     *
+     * @param {Array} args... logging arguments.
+     */
     error: (...args: unknown[]) => void;
 };
 
@@ -42,15 +112,92 @@ declare interface ScriptValue {
 type NewBean = <T = unknown, Bean extends keyof XpBeans | string = string>(bean: Bean) =>
     Bean extends keyof XpBeans ? XpBeans[Bean] : T;
 
+/**
+ * Javascript to Java bridge functions.
+ *
+ * @example
+ * var bean = __.newBean('com.enonic.xp.MyJavaUtils');
+ *
+ * @example
+ * return __.toNativeObject(bean.findArray(arrayName));
+ *
+ * @global
+ * @namespace
+ */
 declare const __: {
+    /**
+     * Creates a new JavaScript bean that wraps the given Java class and makes its methods available to be called from JavaScript.
+     */
     newBean: NewBean;
-    toNativeObject: <T = unknown>(beanResult: T) => T;
+    /**
+     * Converts arrays or complex Java objects to JSON.
+     * @param value Value to convert
+     */
+    toNativeObject: <T = unknown>(value: T) => T;
+    /**
+     * Converts JSON to a Java Map structure that can be used as parameters to a Java method on a bean created with newBean.
+     * @param value Value to convert
+     */
     toScriptValue: <T = object>(value: T) => ScriptValue;
+    /**
+     * Add a disposer that is called when the app is stopped.
+     * @param callback Function to call
+     */
     disposer: (callback: (...args: unknown[]) => unknown) => void;
+    /**
+     * Converts a JavaScript variable that is undefined to a Java <code>null</code> object.
+     * If the JavaScript variable is defined, it is returned as is.
+     * @param value Value to convert
+     */
     nullOrValue: <T = object>(value: T) => T | null | undefined;
+
+    /**
+     * Doc registerMock.
+     *
+     * @param name Name of mock.
+     * @param value Value to register.
+     */
+    registerMock: (name: string, value: object) => void
 };
 
 declare type XpRequire = <Key extends keyof XpLibraries | string = string>(path: Key) =>
     Key extends keyof XpLibraries ? XpLibraries[Key] : unknown;
 
+/**
+ * This globally available function will load a JavaScript file and return the exports as objects.
+ * The function implements parts of the `CommonJS Modules Specification`.
+ *
+ * @example
+ * // Require relative to this
+ * var other = require('./other.js');
+ *
+ * @example
+ * // Require absolute
+ * var other = require('/path/to/other.js');
+ *
+ * @example
+ * // Require without .js extension
+ * var other = require('./other');
+ *
+ * @param {string} path Path for javascript file (relative or absolute and .js ending is optional).
+ * @returns {object} Exports from loaded javascript.
+ * @global
+ */
 declare const require: XpRequire;
+
+/**
+ * Resolves a path to another file. Can use relative or absolute path.
+ *
+ * @example
+ * // Resolve relative to this
+ * var path = resolve('./other.html');
+ *
+ * @example
+ * // Reslove absolute
+ * var path = resolve('/path/to/other.html');
+ *
+ * @param {string} path Path to resolve.
+ * @returns {*} Reference to an object.
+ * @global
+ */
+declare const resolve: (path: string) => object;

package/package.json

@@ -1,32 +1,33 @@
-{
-    "name": "@enonic-types/global",
-    "version": "0.1.1",
-    "description": "Type definitions for global.",
-    "types": "global.d.ts",
-    "files": [
-        "global.d.ts"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/enonic/xp.git#master"
-    },
-    "keywords": [
-        "enonic",
-        "enonic-xp",
-        "global",
-        "common",
-        "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"
-    }
-}
+{
+    "name": "@enonic-types/global",
+    "version": "7.11.0-B2",
+    "description": "Global variables and functions type definition.",
+    "types": "global.d.ts",
+    "files": [
+        "global.d.ts"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/enonic/xp.git#master"
+    },
+    "keywords": [
+        "enonic",
+        "enonic-xp",
+        "global",
+        "common",
+        "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",
+    "dependencies": {},
+    "publishConfig": {
+        "access": "public"
+    }
+}