@enonic-types/lib-common 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# Enonic XP lib-common TS types
+
+> TypeScript definitions for `lib-common` library of Enonic XP
+
+## Install
+
+```bash
+npm i --save-dev @enonic/lib-common
+```
+
+## 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-common"
+    ]
+  }
+}
+```
+
+### 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-common"
+    ]
+  }
+}
+```
+
+`example.ts`
+```ts
+const {sanitize} = require('/lib/xp/common');
+```
+
+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-common"
+    ]
++   "baseUrl": "./",
++   "paths": {
++     "/lib/xp/common": ["node_modules/@enonic-types/lib-common"],
++   }
+  }
+}
+```
+
+`example.ts`
+```ts
+import {sanitize} from '/lib/xp/common';
+```
+
+Setting `baseUrl` and `paths` will allow the `tsc` to keep the valid paths in the resulting JavaScript files.

package/common.d.ts

@@ -0,0 +1,24 @@
+declare global {
+    interface XpLibraries {
+        '/lib/xp/common': typeof import('./common');
+    }
+}
+/**
+ * Transform a text string so that it can be safely used in cases where the range of accepted characters is restricted.
+ *
+ * Some usage examples are: as an XP content or node name, as a principal name, in a URL or in a filesystem path.
+ *
+ * The following changes will be applied to the input text:
+ * - convert characters to lowercase (according to the rules of the default locale)
+ * - replace punctuation symbols and blank spaces with the hyphen character ('-')
+ * - remove some unsafe and invisible Unicode characters
+ * - strip duplicated hyphen characters
+ * - remove diacritic characters
+ * - map letters to the English alphabet (ASCII encoding)
+ *
+ * @example-ref examples/common/sanitize.js
+ *
+ * @param {string} text Text string to sanitize.
+ * @returns {string} Sanitized text.
+ */
+export declare function sanitize(text: string): string;

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "@enonic-types/lib-common",
+    "version": "0.1.0",
+    "description": "Type definitions for lib-common.",
+    "types": "common.d.ts",
+    "files": [
+        "common.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-common",
+        "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"
+    }
+}