{"_id":"@amsom-habitat/oracle-function-calling","name":"@amsom-habitat/oracle-function-calling","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@amsom-habitat/oracle-function-calling","version":"1.0.1","description":"Appel de fonctions stockées Oracle depuis Node : binds natifs (dont CLOB/BLOB), lecture du retour et traduction des erreurs ORA (portage Node du package PHP amsom-habitat/oracle-function-calling).","keywords":["oracle","oracledb","plsql","stored-procedures","clob","blob","nestjs","amsom"],"license":"UNLICENSED","author":{"name":"Amsom Habitat"},"repository":{"type":"git","url":"git+https://gitlab.com/amsom-package/oracle-function-calling-node.git","directory":"package_src"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js","default":"./dist/index.js"},"./knex":{"types":"./dist/knex/index.d.ts","require":"./dist/knex/index.js","default":"./dist/knex/index.js"},"./nest":{"types":"./dist/nest/index.d.ts","require":"./dist/nest/index.js","default":"./dist/nest/index.js"}},"engines":{"node":">=18"},"scripts":{"build":"tsc","lint":"eslint","lint:fix":"eslint --fix","test":"jest","prepublishOnly":"npm run build"},"dependencies":{"@types/oracledb":"^6.9.1"},"peerDependencies":{"@nestjs/common":"^10.0.0 || ^11.0.0","knex":"^3.0.0","oracledb":"^6.0.0 || ^7.0.0"},"peerDependenciesMeta":{"@nestjs/common":{"optional":true},"knex":{"optional":true}},"devDependencies":{"@eslint/js":"^9.39.0","@nestjs/common":"^11.1.28","@types/jest":"^30.0.0","@types/node":"^26.1.1","eslint":"^9.39.0","globals":"^15.15.0","jest":"^30.4.2","knex":"^3.3.0","oracledb":"^7.0.1","reflect-metadata":"^0.2.2","rxjs":"^7.8.2","ts-jest":"^29.4.12","typescript":"^5.9.3","typescript-eslint":"^8.65.0"},"_id":"@amsom-habitat/oracle-function-calling@1.0.1","gitHead":"bb4f79008e72c33e3ef3ac3d3c4c7af5705c5012","bugs":{"url":"https://gitlab.com/amsom-package/oracle-function-calling-node/issues"},"homepage":"https://gitlab.com/amsom-package/oracle-function-calling-node#readme","_nodeVersion":"24.20.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-0+1YvHk65Na2R0Evo000Npwp1+b5FaGRKBICSpk2TaXiiCRv90/NNFknfyFB0gh6kIf8/auzeueS9TILFWXLLw==","shasum":"ad13bdf93f346e02fb2a6dad631cb52144e41ce1","tarball":"https://registry.npmjs.org/@amsom-habitat/oracle-function-calling/-/oracle-function-calling-1.0.1.tgz","fileCount":26,"unpackedSize":49585,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCC3tlCPAXHzPC4UPw4Ei0nS5qZHyZqmfzxcSb3Qpm6rgIhAKkOPTSNsqjTmsspKDiAJYxTEl/TtISTjcsB98/OsDZn"}]},"_npmUser":{"name":"amsom-habitat","email":"dev@amsom-habitat.fr"},"directories":{},"maintainers":[{"name":"amsom-habitat","email":"dev@amsom-habitat.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/oracle-function-calling_1.0.1_1788443269508_0.18655890389260987"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-03T13:47:49.314Z","1.0.1":"2026-09-03T13:47:49.628Z","modified":"2026-09-03T13:47:49.846Z"},"maintainers":[{"name":"amsom-habitat","email":"dev@amsom-habitat.fr"}],"description":"Appel de fonctions stockées Oracle depuis Node : binds natifs (dont CLOB/BLOB), lecture du retour et traduction des erreurs ORA (portage Node du package PHP amsom-habitat/oracle-function-calling).","homepage":"https://gitlab.com/amsom-package/oracle-function-calling-node#readme","keywords":["oracle","oracledb","plsql","stored-procedures","clob","blob","nestjs","amsom"],"repository":{"type":"git","url":"git+https://gitlab.com/amsom-package/oracle-function-calling-node.git","directory":"package_src"},"author":{"name":"Amsom Habitat"},"bugs":{"url":"https://gitlab.com/amsom-package/oracle-function-calling-node/issues"},"license":"UNLICENSED","readme":"# @amsom-habitat/oracle-function-calling\n\nAppel de **fonctions stockées Oracle** depuis Node : binds natifs (dont CLOB et BLOB), lecture du retour\nselon la convention `{ \"data\": … }` des fonctions `AH_*`, et traduction des codes `ORA-` en statuts HTTP.\n\nPortage Node du package Composer [`amsom-habitat/oracle-function-calling`](https://gitlab.com/amsom-package/oraclefunctioncalling)\nutilisé par les applications Symfony maison. Deux différences de fond, dues au driver `node-oracledb` :\n\n- **plus de découpage 32 ko ni de conversion base64 → CLOB → BLOB** : les LOB sont bindés nativement, donc\n  `call()`, `largeCall()` et `fileCall()` fusionnent en un seul `callFunction()` ;\n- **plus d'échappement de quotes** : les valeurs passent en *bind variables* au lieu d'être concaténées dans\n  le littéral SQL, ce qui supprime au passage tout risque d'injection.\n\n## Installation\n\n```sh\nnpm install @amsom-habitat/oracle-function-calling\n```\n\n`oracledb` est une **peerDependency** (le pool est celui de l'application, pas celui du package) :\n\n```sh\nnpm install oracledb\n```\n\n`knex` et `@nestjs/common` sont des peerDependencies **optionnelles** : elles ne sont requises que si vous\nimportez le sous-export correspondant.\n\n## Configuration\n\nLe package ne lit aucune variable d'environnement et ne crée aucune connexion. Il reçoit un\n`ConnectionProvider`, c'est-à-dire de quoi emprunter puis rendre une connexion :\n\n| Option | Type | Défaut | Rôle |\n|---|---|---|---|\n| `connection` | `ConnectionProvider` | — | source des connexions (**obligatoire**) |\n| `logger` | `LoggerLike` | aucun | journal des erreurs brutes du driver |\n| `maxOutputSize` | `number` | `32767` | taille max du paramètre de sortie (`VARCHAR2` PL/SQL) |\n\nDeux fabriques sont fournies :\n\n```ts\nimport { fromOraclePool } from '@amsom-habitat/oracle-function-calling'\nimport { fromKnex } from '@amsom-habitat/oracle-function-calling/knex'\n```\n\n## Utilisation\n\n### Node « nu »\n\n```ts\nimport oracledb from 'oracledb'\nimport { OracleFunctionCalling, fromOraclePool } from '@amsom-habitat/oracle-function-calling'\n\nconst pool = await oracledb.createPool({ user, password, connectString })\nconst oracle = new OracleFunctionCalling({ connection: fromOraclePool(pool), logger: console })\n\nconst resultat = await oracle.callFunction('AH_CALLY_INDIVIDU_TELMOBILE_MAJ', [\n  idIndividu,\n  '0600000000',\n])\n// → { data: … }\n```\n\n### Au-dessus d'un pool Knex existant\n\nUn seul pool sert alors les lectures (query builder) et les appels de fonctions, au lieu d'ouvrir un\ndeuxième jeu de sessions Oracle :\n\n```ts\nimport { fromKnex } from '@amsom-habitat/oracle-function-calling/knex'\n\nconst oracle = new OracleFunctionCalling({ connection: fromKnex(db) })\n```\n\n### NestJS\n\n```ts\n// app.module.ts\nimport { OracleModule, oracleErrorToHttpException } from '@amsom-habitat/oracle-function-calling/nest'\nimport { fromKnex } from '@amsom-habitat/oracle-function-calling/knex'\n\n@Module({\n  imports: [\n    OracleModule.forRootAsync({\n      isGlobal: true,\n      inject: [KNEX_TOKEN],\n      useFactory: (db: Knex) => ({\n        connection: fromKnex(db),\n        mapError: oracleErrorToHttpException, // optionnel, voir « Erreurs »\n      }),\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n```ts\n// un service métier\nimport { OracleService } from '@amsom-habitat/oracle-function-calling/nest'\n\n@Injectable()\nexport class SollicitationService {\n  constructor(private readonly oracle: OracleService) {}\n\n  creer(dto: CreerSollicitationDto) {\n    return this.oracle.callFunction('AH_CALLY_SOLLICITATION_CREER', [\n      dto.idIndividu,\n      dto.motif,\n      { type: 'clob', value: dto.commentaire }, // gros texte → CLOB natif\n    ])\n  }\n}\n```\n\n### Paramètres LOB\n\n```ts\nawait oracle.callFunction('AH_CALLY_DOCUMENT_AJOUT', [\n  idDossier,\n  { type: 'clob', value: gabaritHtml },                  // > 32 ko de texte\n  { type: 'blob', value: Buffer.from(base64, 'base64') }, // fichier binaire\n])\n```\n\n## Erreurs\n\n| Cas | Erreur levée | Contenu |\n|---|---|---|\n| Retour JSON **sans** clé `data` | `OracleCallError` | `payload` = corps rendu par la fonction |\n| Retour vide ou non-JSON | `OracleCallError` | `payload` = chaîne brute |\n| Échec du driver (`ORA-…`) | `OracleDriverError` | `cause` = erreur `oracledb` d'origine |\n\nLe succès se juge à la **présence de la clé `data`**, et à rien d'autre : c'est la convention des fonctions\n`AH_*`, et le package PHP appliquait déjà celle-là. Un corps sans `data` et sans clé d'erreur est donc un\néchec.\n\nTraduction HTTP fournie (utilisable telle quelle, ou remplacée) :\n\n```ts\nimport { oracleErrorToHttp } from '@amsom-habitat/oracle-function-calling'\n\noracleErrorToHttp(err)\n// ORA-20xxx (RAISE_APPLICATION_ERROR) → 400 + message métier\n// ORA-00001 (unicité)                 → 409\n// ORA-01722 / 01858 / 01400 / 06502…  → 400 « Paramètre invalide »\n// autre erreur Oracle                 → 500 « Erreur interne du serveur »\n// erreur non-Oracle                   → null\n```\n\nCôté NestJS, `mapError` permet de convertir `OracleCallError` / `OracleDriverError` en exceptions de\nl'application. C'est le point d'accroche des API qui doivent conserver au caractère près la forme de\nréponse d'une v1 (statut, enveloppe, texte du message). Sans `mapError`, l'erreur d'origine remonte telle\nquelle.\n\n## API publique\n\n### `@amsom-habitat/oracle-function-calling`\n\n| Export | Type | Rôle |\n|---|---|---|\n| `OracleFunctionCalling` | classe | `callFunction(name, params?)` |\n| `fromOraclePool(pool)` | fonction | `ConnectionProvider` sur un pool `oracledb` |\n| `OracleCallError` | classe | échec métier (`payload`, `functionName`) |\n| `OracleDriverError` | classe | erreur driver (`cause`, `functionName`) |\n| `oracleErrorToHttp(err)` | fonction | `{ status, message } \\| null` |\n| `cleanOraMessage(raw)` | fonction | message métier d'un texte `ORA-` |\n| `ConnectionProvider`, `OracleParam`, `LoggerLike`, `OracleFunctionCallingOptions`, `OracleHttpError` | types | — |\n\n### `@amsom-habitat/oracle-function-calling/knex`\n\n| Export | Rôle |\n|---|---|\n| `fromKnex(db)` | `ConnectionProvider` sur un pool Knex (via `client.acquireConnection()`) |\n\n### `@amsom-habitat/oracle-function-calling/nest`\n\n| Export | Rôle |\n|---|---|\n| `OracleModule.forRoot(options)` / `forRootAsync(options)` | module fournissant `OracleService` |\n| `OracleService` | `callFunction(name, params?)`, injectable |\n| `oracleErrorToHttpException(err)` | `mapError` prêt à l'emploi |\n| `ORACLE_MODULE_OPTIONS` | jeton d'injection des options |\n\n## Développement\n\n```sh\nnpm install\nnpm run build   # tsc → dist/ (CommonJS + .d.ts)\nnpm run lint\nnpm test        # jest\n```\n\nLe package est publié en **CommonJS** : les API NestJS maison sont en CJS, un paquet ESM-only n'y serait\npas importable. La carte `exports` du `package.json` laisse la place à un build ESM ultérieur.\n\n## Versionnage\n\nSemVer, une entrée par version dans [`changelog.md`](./changelog.md) (`## VX.Y.Z - JJ/MM/AAAA`).\n`check-version.sh` refuse une publication dont la version n'est pas décrite dans le changelog, ou qui porte\nun suffixe de pré-release.\n\n```sh\n# depuis package_src/, après avoir bumpé la version et complété le changelog\nmake publish        # main : lint + build + test + check-version + tag git + npm publish\nmake alpha_publish  # dev  : publication d'une beta\n```\n\nLe tag git est posé sur le dépôt GitLab, le paquet est publié sur npmjs sous le scope `@amsom-habitat`.\n","readmeFilename":"README.md","_rev":"1-63d38d9f21ba8a6328dea244c159cb68"}