qlcodes 1.1.3 → 1.2.0

package/README.md

@@ -8,10 +8,9 @@ The module is built from authoritative vendor documentation (IBM, PostgreSQL, Or
 
 The project aims to cover sql states for most of RDBMS [drivers supported by **Typeorm** such as Google Spanner](https://typeorm.io/docs/drivers/google-spanner).
 Find bellow the actual coverage:
-
-🕓 MySQL | 🕓 MariaDB | ✅ PostgreSQL | 🕓 CockroachDB (Postgres-compatible)
-🕓 Microsoft SQL Server | ✅ Oracle | 🕓 SQLite | 🕓 SAP HANA | 🕓 Google Spanner
-✅ IBM*
+               
+🕓 MySQL | ✅ MariaDB | ✅ PostgreSQL | 🕓 CockroachDB (Postgres-compatible)
+🕓 Microsoft SQL Server | ✅ Oracle | 🕓 SQLite | ✅ SAP HANA | ✅ Google Spanner | ✅ IBM*
 >( \* ) IBM defines and publishes SQLSTATE codes as part of the SQL standard, so their The codes should covere IBM products such as DB2, IBM Informix, IBM Netezza, IBM i (AS/400) .
 
 ## Installation
@@ -24,9 +23,9 @@ $ npm install qlcodes
 
 ```js
 import { lens } from "qlcodes";
-    
+
 const state = lens("42501");
-    
+
 console.log(state);
 ```
 
@@ -34,11 +33,25 @@ Output :
 
 ```js
 {
-  code: "42501",
-  keys: [ "insufficient_privilege" ],
-  use: [ "ibm", "postgres" ],
-  reason: "The authorization ID does not have the privilege to perform the specified operation on the identified object.",
-  qlcs: "qlcodes_sucess"
+  "code": "42501",
+  "qlcs": "qlcodes_success",
+  "matches": [
+    {
+      "code": "42501",
+      "keys": [
+        "insufficient_privilege",
+        "authorization_id_does_not_have_privilege_to_perform_specified_operation_on_identified_object"
+      ],
+      "reasons": [
+        "The authorization ID does not have the privilege to perform the specified operation on the identified object."
+      ],
+      "use": [
+        "pgsql",
+        "ibm"
+      ],
+      "class": "42 - Syntax Error or Access Rule Violation"
+    }
+  ]
 }
 ```
 
@@ -50,7 +63,7 @@ This guarantees that lens() always returns a predictable object shape.
 There are three mismatch levels that we detect.
 
 **Format** : The provided code is malformed and is not validate the expression /[0-9A-Z]{5}/
-  
+
 > ℹ️ ["SQLSTATE values are comprised of a two-character class code value, followed by a three-character subclass code value. (ISO/IEC 9075:1992)"](https://www.ibm.com/docs/en/db2-for-zos/12.0.0?topic=codes-sqlstate-values-common-error)
 
 ```js
@@ -61,28 +74,9 @@ Output:
 
 ```js
 {
-  code: "123456",
-  keys: [],
-  qlcs: "qlcodes_malformed",
-  use: [],
-  r
-```
-
-**Class** : The provided code matches no code class
-
-```js
-console.log(lens("ABCDE"));
-```
-
-Output:
-
-```js
-{
-  code: "ABCDE",
-  keys: [],
-  qlcs: "qlcodes_no_class_found",
-  use: [],
-  reason: "The code 'ABCDE' does not match any entries in qlcodes. This may be a qlcode issue only to provide you with the correct information"
+  "code": "123456",
+  "qlcs": "qlcodes_malformed",
+  "matches": []
 }
 ```
 
@@ -96,11 +90,9 @@ Output:
 
 ```js
 {
-  code: "2000U",
-  keys: [],
-  qlcs: "qlcodes_no_code_found",
-  use: [],
-  reason: "The code '2000U' does not match any entries in qlcodes. This may be a qlcode issue only to provide you with the correct information"
+  "code": "ABCDE",
+  "qlcs": "qlcodes_no_code_found",
+  "matches": []
 }
 ```
 
@@ -116,14 +108,11 @@ Output:
 || **code** — normalized SQLSTATE, or `-1` if not found
 || **keys** — semantic identifiers
 || **use** — `DBMS` where the code is applicable
-|| **reason** — human-readable explanation
+|| **reasons** — human-readable explanations
 || **qlcs** — 'qlcode status', shows the lens call status
 
 ## Customization & Rebuild (Contributors)
 
-> ⚠️ Do not modify files inside node_modules.
-> Changes will be lost on reinstall.
-
 If you want to extend or adjust the reference data:
 
 1) Clone the repository
@@ -134,32 +123,37 @@ $ cd qlcodes
 $ npm install
 ```
 
-2) Modify files:
+2) Adapt the column (headers) configuration.
+- `.qlCodes` file (root) : gives the configuration of CSVs headers/columns (with their format and aliases)
+- `src/constants.mjs` : gives the configuration of the options passed throught `@maze014/domFetch` to fetch the documentation table of codes for the matching RDBMs.
+
+3) Run the dev script to set everything up.
+```bash
+$ npm run dev
+```
+This action will generate the folowing resources folders :
+- HTML : files from which a DOM can be fetched via domFetch.
+- CSV : CSVs files generated from the build script. These files can be modified according updated info. 
 
-- under references/
-    -> CSV files generated from vendor documentation
-- under src/
-    -> transformation and normalization logic
 
-> ⚠️ follow the data modification pipeline describe by the `build.sh` script.
-> unless you know what you know what you are doing.
+4) Rebuild the module
 
-3) Rebuild the module
 
 ```bash
-$ npm run build
+# generate the qlCodes.json
+$ npm run build -- --prod
 ```
 
 ### Quality of life
 
-You may pass argument to the build script to enforce a few behaviours to help you seing through the process...
+By default, the build script has no flag passed but
+You may pass flag argument to the build script to enforce a few behaviours to help you seing through the processor...
 
 |argument|effect|
 |-|-|
 |`--debug`|prevents the cleanup of middle stage file created during the data processing|
-|`--make-keys`|allows the creation of keys when a description is given...through the 'generate' step (`generate.cjs`)|
+|`--prod`|will destroy the resources folder in order to keep things clean|
 
-Use your customized build via a local dependency or a forked package.
 
 ---
 
@@ -183,6 +177,15 @@ Use your customized build via a local dependency or a forked package.
   [Oracle appendix](https://docs.oracle.com/cd/E15817_01/appdev.111/b31228/appd.htm)
   11g Release 1 (11.1)
 
+- MariaDb
+  [MariaDB Error Code Reference](https://mariadb.com/docs/server/reference/error-codes/mariadb-error-code-reference)
+
+- Google Spanner
+  [Spanner error codes](https://docs.cloud.google.com/spanner/docs/error-codes)
+
+- SAP Hana
+  [SAP HANA SQL Reference Guide for SAP HANA Platform](https://help.sap.com/docs/SAP_HANA_PLATFORM/4fe29514fd584807ac9f2a04f6754767/20a78d3275191014b41bae7c4a46d835.html) V2.0 SPS 08
+
 ---
 
 ## License

package/dist/index.mjs

@@ -0,0 +1,70 @@
+import { readFileSync } from "fs";
+
+const data = JSON.parse(readFileSync("./qlCodes.json"));
+
+export const lens = (code) => {
+	let response = {
+		code,
+		qlcs: "",
+		matches: [],
+	};
+
+	try {
+		// ---- validation ----
+		if (
+			code === "" ||
+			(!code && code !== "0") ||
+			!/^[A-Z0-9]{5}$/.test(`${code}`.padStart(5, "0"))
+		) {
+			throw "qlcodes_malformed";
+		}
+
+		const paddedCode = `${code}`.padStart(5, "0");
+
+		// ---- find matching class ----
+		const classEntry = Object.entries(data).find(([id]) =>
+			paddedCode.startsWith(id)
+		);
+
+		const classesToSearch = [];
+
+		if (classEntry) {
+			classesToSearch.push({
+				id: classEntry[0],
+				data: classEntry[1],
+			});
+		}
+
+		// Always include NA as fallback / collision source
+		if (data["NA"]) {
+			classesToSearch.push({
+				id: "NA",
+				data: data["NA"],
+			});
+		}
+
+		// ---- collect all matches ----
+		for (const cls of classesToSearch) {
+			const hits = cls.data.messageSet.filter(
+				(x) => x.code === paddedCode || x.code === code
+			);
+
+			for (const hit of hits) {
+				response.matches.push({
+					...hit,
+					class: `${cls.id} - ${cls.data.label}`,
+				});
+			}
+		}
+
+		if (response.matches.length === 0) {
+			throw "qlcodes_no_code_found";
+		}
+
+		response.qlcs = "qlcodes_success";
+	} catch (err) {
+		response.qlcs = typeof err === "string" ? err : "qlcodes_unexpected_error";
+	}
+
+	return response;
+};