@enonic-types/lib-grid 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# Enonic XP lib-grid TS types
+
+> TypeScript definitions for `lib-grid` library of Enonic XP
+
+## Install
+
+```bash
+npm i --save-dev @enonic/lib-grid
+```
+
+## Use
+
+Add the corresponding types to your `tsconfig.json` file that is used for application's server-side TypeScript code.
+
+`tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@enonic-types/lib-grid"
+    ]
+  }
+}
+```
+
+### Require and custom imports
+
+To make `require` work out of box, you must install and add the `@enonic-types/global` types. Aside from providing definitions for XP global
+objects, e.g. `log`, `app`, `__`, etc, requiring library by the default path will return typed object.
+
+`tsconfig.json`
+
+```diff
+{
+  "compilerOptions": {
+    "types": [
++     "@enonic-types/global"
+      "@enonic-types/lib-grid"
+    ]
+  }
+}
+```
+
+`example.ts`
+
+```ts
+const {getMap} = require('/lib/xp/grid');
+```
+
+More detailed explanation on how it works and how to type custom import function can be
+found [here](https://github.com/enonic/xp/tree/master/modules/lib/typescript/README.md).
+
+### ES6-style import
+
+If you are planning to use `import` in your code and transpile it with the default `tsc` TypeScript compiler, you'll need to add proper
+types mapping to your configuration.
+
+`tsconfig.json`
+
+```diff
+{
+  "compilerOptions": {
+    "types": [
+      "@enonic-types/lib-grid"
+    ]
++   "baseUrl": "./",
++   "paths": {
++     "/lib/xp/grid": ["node_modules/@enonic-types/lib-grid"],
++   }
+  }
+}
+```
+
+`example.ts`
+
+```ts
+import {getMap} from '/lib/xp/grid';
+```
+
+Setting `baseUrl` and `paths` will allow the `tsc` to keep the valid paths in the resulting JavaScript files.

package/grid.d.ts

@@ -0,0 +1,71 @@
+declare global {
+    interface XpLibraries {
+        '/lib/xp/grid': typeof import('./grid');
+    }
+}
+export declare type SharedMapValueType = string | number | boolean | object | null;
+export declare type SharedMapModifierFn = (oldValue: SharedMapValueType) => SharedMapValueType;
+export interface SetParams {
+    key: string;
+    value: SharedMapValueType;
+    ttlSeconds?: number;
+}
+export interface ModifyParams {
+    key: string;
+    func: SharedMapModifierFn;
+    ttlSeconds?: number;
+}
+export declare class SharedMap {
+    private map;
+    /**
+     * Creates an instance of SharedMap which are shared across all applications and even cluster nodes.
+     *
+     * WARNING: Due to distributed nature of the Shared Map not all types of keys and values can be used. Strings, numbers, and pure JSON objects are supported. There is no runtime check for type compatibility due to performance reasons. The developer is also responsible for not modifying shared objects (keys and values) in place.
+     *
+     * @param mapId - map identifier
+     * @constructor
+     */
+    constructor(mapId: string);
+    /**
+     * Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
+     *
+     * @param {string} key - key the key whose associated value is to be returned
+     * @returns {string|number|boolean|JSON|null} the value to which the specified key is mapped, or null if this map contains no mapping for the key
+     */
+    get(key: string): SharedMapValueType;
+    /**
+     * Puts an entry into this map with a given time to live (TTL).
+     * If value is null, the existing entry will be removed.
+     *
+     * @param {object} params JSON with the parameters.
+     * @param {string} params.key key of the entry
+     * @param {string|number|boolean|JSON|null} params.value value of the entry
+     * @param {number} [params.ttlSeconds] maximum time to live in seconds for this entry to stay in the map. (0 means infinite, negative means map config default or infinite if map config is not available)
+     */
+    set(params: SetParams): void;
+    /**
+     * Attempts to compute a mapping for the specified key and its current mapped value.
+     *
+     * @param {object} params JSON with the parameters.
+     * @param {string} params.key  key of the entry
+     * @param {function} params.func mapping function that accepts the existing mapped value (or null, if there is no associated mapping).
+     *                            The returned value replaces the existing mapped value for the specified key.
+     *                            If returned value is null then the value is removed from the map
+     * @param {number} [params.ttlSeconds] maximum time to live in seconds for this entry to stay in the map. (0 means infinite, negative means map config default or infinite if map config is not available)
+     * @returns the new value to which the specified key is mapped, or null if this map no longer contains mapping for the key
+     */
+    modify(params: ModifyParams): SharedMapValueType;
+    /**
+     * Removes the mapping for the key from this map if it is present.
+     *
+     * @param {string} key the key whose associated value is to be removed
+     */
+    delete(key: string): void;
+}
+/**
+ * Returns an instance of SharedMap by the specified map identifier.
+ *
+ * @param {string} mapId map identifier
+ * @returns {SharedMap} an instance of SharedMap
+ */
+export declare function getMap(mapId: string): SharedMap;

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "@enonic-types/lib-grid",
+    "version": "0.1.0",
+    "description": "Type definitions for lib-grid.",
+    "types": "grid.d.ts",
+    "files": [
+        "grid.d.ts"
+    ],
+    "scripts": {
+        "pre": "npm run --prefix ../ pre",
+        "packlist": "npx npm-packlist"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/enonic/xp.git#master"
+    },
+    "keywords": [
+        "enonic",
+        "enonic-xp",
+        "lib-grid",
+        "grid",
+        "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"
+    }
+}