qlcodes 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jean Luc Emmanuel VERHANNEMAN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# QLCodes
+
+A small utility that unifies SQL error codes (SQLSTATE) from different DBMS into a single, normalized structure through a curated dataset constructed at build time.
+
+The module is built from authoritative vendor documentation (IBM, PostgreSQL, Oracle) and generates static reference data at build time. Find references bellow.
+
+## References
+
+- IBM
+  [Listing of SQLSTATE values](https://www.ibm.com/docs/en/i/7.6.0?topic=codes-listing-sqlstate-values#cc__classcode00)
+  (Last Updated: 2025-09-29)
+
+- Postgres codes
+  [Appendix A. PostgreSQL Error Codes](https://www.postgresql.org/docs/10/static/errcodes-appendix.html)
+  (V.10)
+
+
+- Oracle
+  [Oracle appendix](https://docs.oracle.com/cd/E15817_01/appdev.111/b31228/appd.htm)
+  11g Release 1 (11.1)
+
+---
+
+## Installation
+
+```bash
+npm install qlcodes
+```
+
+## Usage
+
+```js
+    import { lens } from "qlcodes";
+    
+    const error = lens("42501");
+    
+    console.log(error);
+```
+
+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."
+}
+```
+
+### Mismatches
+
+If the provided SQLSTATE does not match any known entry, we return a normalized fallback object
+This guarantees that lens() always returns a predictable object shape.
+
+```js
+const error = lens("XXXXX");
+
+console.log(error);
+```
+
+Output:
+
+```js
+{
+  code: "-1",
+  keys: ["qlcodes_not_found"],
+  use: [],
+  reason: "The code 'XXXXX' does not match any entries in qlcodes. This may be a qlcode issue only to provide you with the correct information"
+}
+```
+
+---
+
+## API
+
+`lens(code: string): QLLens`
+|Parameters|Returns|
+|-|-|
+|**code** SQLSTATE error code | A structured error description|
+|| **code** — normalized SQLSTATE, or `-1` if not found
+|| **keys** — semantic identifiers
+|| **use** — `DBMS` where the code is applicable
+|| **reason** — human-readable explanation
+
+## 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
+
+```bash
+$ git clone <repository-url>
+$ cd qlcodes
+$ npm install
+```
+
+2) Modify files:
+
+- 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.
+
+3) Rebuild the module
+```bash
+$ npm run build
+```
+
+### Quality of life
+You may pass argument to the build script to enforce a few behaviours to help you seing through the process...
+|argument|effect|
+|-|-|
+|--debug|prevent the cleanup of middle stage file created during the data processing|
+|--make-keys|allow the creation of keys when a description is given...through the 'generate' step (`generate.cjs`)|
+
+
+
+Use your customized build via a local dependency or a forked package.
+
+---
+
+## License
+[MIT 2025](https://github.com/ManuUseGitHub/QLCodes?tab=MIT-1-ov-file#readme)

package/build.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+# Colors
+GREEN="\033[0;32m"
+BLUE="\033[0;34m"
+YELLOW="\033[1;33m"
+RED="\033[0;31m"
+NC="\033[0m"
+CHECK="${GREEN}✔${NC}"
+CROSS="${RED}✖${NC}"
+
+DIR="$( cd "$( dirname "$0" )" && pwd )"
+
+start_time=$(date +%s)
+
+# ---- BOX FUNCTION -----------------------------------------------------------
+
+print_box () {
+    local text="$1"
+    local fixed_width="$2"
+
+    # Strip ANSI colors for measuring
+    local plain_text=$(echo -e "$text" | sed 's/\x1b\[[0-9;]*m//g')
+    local content_len=${#plain_text}
+
+    # Determine final width (content width if no fixed width)
+    local box_width
+    if [[ -n "$fixed_width" && "$fixed_width" -gt "$content_len" ]]; then
+        box_width=$fixed_width
+    else
+        box_width=$content_len
+    fi
+
+    # Compute padding for centering
+    local total_pad=$(( box_width - content_len ))
+    local left_pad=$(( total_pad / 2 ))
+    local right_pad=$(( total_pad - left_pad ))
+
+    # Generate padding spaces
+    local left_spaces=$(printf "%*s" "$left_pad" "")
+    local right_spaces=$(printf "%*s" "$right_pad" "")
+
+    # Build border
+    local border=$(printf '%*s' "$box_width" '' | tr ' ' '_')
+    local blank=$(printf '%*s' "$box_width" '' | tr ' ' ' ')
+    echo -e "${GREEN}" 
+    echo " _$border""_"
+    echo "/ $blank"" \\" 
+    echo "  ${left_spaces}${text}${right_spaces}"
+    echo "\\_$border""_/" 
+    echo -e "${NC}"
+}
+
+# ---- SCRIPT START -----------------------------------------------------------
+
+DEBUG=false
+MAKE_KEYS=false
+
+for arg in "$@"; do
+  case $arg in
+    --debug)
+      DEBUG=true
+      ;;
+    --make-keys)
+      MAKE_KEYS=true
+      ;;
+  esac
+done
+
+export DEBUG && export MAKE_KEYS
+
+clear
+print_box "$(basename "$0") execution" 64                                                             
+
+echo -e "MODES"
+echo -e "${YELLOW} $@ ${NC}"
+
+SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
+echo -e "${BLUE}Creating codes from $SCRIPT_DIR/references/IBM_errors.csv ${NC}"
+cd src
+
+node readFile.mjs ../references/IBM_errors.csv |\
+node fileTransformer/sanitize.mjs |\
+node generate.cjs --flag "ibm" |\
+node fileTransformer/stopNamedKeys.mjs> "$DIR/output1.txt"
+
+echo -e "$CHECK done"
+
+echo -e "${BLUE}Creating codes from $SCRIPT_DIR/references/PSQL_errors.csv ${NC}"
+node readFile.mjs ../references/PSQL_errors.csv |\
+node generate.cjs --flag "postgres" > "$DIR/output2.txt"
+
+echo -e "$CHECK done"
+
+echo -e "${BLUE}Creating codes from $SCRIPT_DIR/references/ORACLE_errors.csv ${NC}"
+node readFile.mjs ../references/ORACLE_errors.csv |\
+node fileTransformer/sanitize2.mjs |\
+node generate.cjs --flag "oracle"> "$DIR/output3.txt"
+
+echo -e "$CHECK done"
+
+echo -e "${BLUE}Composition of the JSON file at $DIR/qlCodes.json${NC}"
+echo {} | node compose.mjs --file "$DIR/output1.txt"|\
+node compose.mjs --file "$DIR/output2.txt" |\
+node compose.mjs --file "$DIR/output3.txt" |\
+node pretty.mjs --file "$DIR/qlCodes.json"
+
+echo -e "$CHECK deleted"
+
+if ! $DEBUG ;
+then
+  echo -e "${BLUE}removing processing files.${NC}"
+  cd .. ; rm "$DIR/output1.txt" ; rm "$DIR/output1.txt.debug.json"
+  cd .. ; rm "$DIR/output2.txt" ; rm "$DIR/output2.txt.debug.json"
+  cd .. ; rm "$DIR/output3.txt" ; rm "$DIR/output3.txt.debug.json"
+  echo -e "$CHECK removed"
+fi
+
+end_time=$(date +%s)
+duration=$((end_time - start_time))
+echo -ne "\nExecution complete in ${YELLOW}${duration}s${NC}$(tput el)\n"                                                                                           
+
+print_box finish 64

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "qlcodes",
+  "version": "1.0.0",
+  "main": "src/index.mjs",
+  "scripts": {
+    "build": "chmod +x ./build.sh; ./build.sh"
+  },
+  "types": "types/index.d.ts",
+  "type": "module",
+  "author": "Jean Luc Emmanuel VERHANNEMAN",
+  "license": "MIT",
+  "description": "A small utility that unifies SQL error codes (SQLSTATE) from different DBMS into a single, normalized structure through a curated dataset constructed at build time. The module is built from authoritative vendor documentation (IBM, PostgreSQL, Oracle) and generates static reference data at build time. Find references bellow.",
+  "keywords": [
+    "postgres",
+    "ibm",
+    "sql",
+    "db",
+    "oracle",
+    "error",
+    "appendix",
+    "codes",
+    "guidance"
+  ]
+}