@enonic-types/global 0.1.0 → 7.11.0-B1

package/README.md

@@ -23,7 +23,7 @@ Add the corresponding types to your `tsconfig.json` file that is used for applic
 }
 ```
 
-> The paths to the `node_mosules` assume that your `tsconfig.json` is placed under your project root.
+> The paths to the `node_modules` assume that your `tsconfig.json` is placed under your project root.
 
 After that, all the global XP variables will be typed.
 
@@ -36,7 +36,8 @@ libraries are also added to your `tsconfig.json`.
 
 ### 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:
+To add support for type resolution for the custom libraries via `require`, you can redeclare the `XpLibraries` interface in global scope,
+which will lead to declaration merging:
 
 ```ts
 declare global {
@@ -46,9 +47,10 @@ 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;
 ```
@@ -63,7 +65,7 @@ interface SomeHelper {
 }
 ```
 
-__Option 1__
+#### Option 1
 
 You can pass the type argument explicitly. This option is a bit cleaner.
 
@@ -71,7 +73,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

@@ -1,18 +1,203 @@
+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>;
+};
+
 /**
- * This project don't include XP libraries definitions and need this interface
- * to properly map imports via require.
+ * Logging functions.
  *
- * 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
+ * // Log with simple message
+ * log.debug('My log message');
  *
  * @example
- * declare global {
- *     interface XpLibraries {
- *         '/lib/xp/event': typeof import('./event');
- *     }
- * }
-*/
-interface XpLibraries {}
+ * // 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;
 
-interface XpBeans {}
+    /**
+     * 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;
+};
+
+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;
+
+/**
+ * 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;
+    /**
+     * 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,10 +1,9 @@
 {
     "name": "@enonic-types/global",
-    "version": "0.1.0",
-    "description": "Type definitions for XP JavaScript global object properties.",
-    "types": "index.d.ts",
+    "version": "7.11.0-B1",
+    "description": "Type definitions for global.",
+    "types": "global.d.ts",
     "files": [
-        "index.d.ts",
         "global.d.ts"
     ],
     "repository": {
@@ -15,6 +14,7 @@
         "enonic",
         "enonic-xp",
         "global",
+        "common",
         "types",
         "typescript"
     ],

package/index.d.ts

@@ -1,54 +0,0 @@
-/// <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;