@astratra/core 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +61 -0
- package/package.json +37 -0
- package/src/AppError.js +12 -0
- package/src/apiResponse.js +16 -0
- package/src/asyncHandler.js +7 -0
- package/src/errorMiddleware.js +29 -0
- package/src/index.d.ts +93 -0
- package/src/index.js +11 -0
- package/src/loadEnv.js +56 -0
- package/src/logger.js +32 -0
- package/src/notFoundMiddleware.js +7 -0
- package/src/requestIdMiddleware.js +24 -0
- package/src/validateMiddleware.js +20 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Astratra
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# @astratra/core
|
|
2
|
+
|
|
3
|
+
Briques de base partagées, indépendantes de tout framework, utilisées par
|
|
4
|
+
tous les autres packages Astratra : format de réponse API, gestion
|
|
5
|
+
d'erreurs, logs, identifiant de requête, validation et chargement de
|
|
6
|
+
variables d'environnement. Aucune base de données, aucun ORM, aucune
|
|
7
|
+
logique métier.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
Dans le monorepo, les autres packages en dépendent via `file:../core`. Hors
|
|
12
|
+
monorepo, ce serait une dépendance npm classique une fois publié.
|
|
13
|
+
|
|
14
|
+
## Contenu
|
|
15
|
+
|
|
16
|
+
```js
|
|
17
|
+
const {
|
|
18
|
+
apiResponse, // (res, statusCode, message, data, success) => envoie une réponse JSON unifiée
|
|
19
|
+
asyncHandler, // (fn) => wrapper middleware Express qui transmet les erreurs à next()
|
|
20
|
+
createLogger, // (serviceName) => { info, warn, error, debug } — no-op si NODE_ENV=test
|
|
21
|
+
AppError, // classe AppError extends Error — porte un statusCode
|
|
22
|
+
errorMiddleware, // gestionnaire d'erreurs Express — masque message/stack en production, logge les 5xx via req.log ou console
|
|
23
|
+
notFoundMiddleware, // gestionnaire 404 Express via apiResponse
|
|
24
|
+
requestIdMiddleware, // attache req.requestId (header X-Request-Id, respecte un id entrant)
|
|
25
|
+
validateMiddleware, // (validations) => exécute des validations express-validator, 400 si échec
|
|
26
|
+
loadEnv // (schema) => lit process.env avec valeurs par défaut/requis/transform/validate
|
|
27
|
+
} = require('@astratra/core');
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Exemple
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
const express = require('express');
|
|
34
|
+
const { apiResponse, asyncHandler, errorMiddleware, notFoundMiddleware, requestIdMiddleware, AppError } = require('@astratra/core');
|
|
35
|
+
|
|
36
|
+
const app = express();
|
|
37
|
+
app.use(requestIdMiddleware);
|
|
38
|
+
|
|
39
|
+
app.get('/ping', asyncHandler(async (req, res) => {
|
|
40
|
+
return apiResponse(res, 200, 'pong', { requestId: req.requestId });
|
|
41
|
+
}));
|
|
42
|
+
|
|
43
|
+
app.get('/boom', asyncHandler(async () => {
|
|
44
|
+
throw new AppError('Quelque chose de précis a cassé', 400);
|
|
45
|
+
}));
|
|
46
|
+
|
|
47
|
+
app.use(notFoundMiddleware);
|
|
48
|
+
app.use(errorMiddleware);
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`errorMiddleware` logge les erreurs serveur (5xx) via `req.log.error` si
|
|
52
|
+
disponible, sinon `console.error`, et ne logge jamais les erreurs client
|
|
53
|
+
(4xx).
|
|
54
|
+
|
|
55
|
+
## Tests
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm test --workspace @astratra/core
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
20 tests, aucune base de données ni réseau requis.
|
package/package.json
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@astratra/core",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Generic core utilities for Astratra SaaS packages.",
|
|
5
|
+
"main": "src/index.js",
|
|
6
|
+
"types": "src/index.d.ts",
|
|
7
|
+
"type": "commonjs",
|
|
8
|
+
"files": [
|
|
9
|
+
"src"
|
|
10
|
+
],
|
|
11
|
+
"scripts": {
|
|
12
|
+
"test": "jest"
|
|
13
|
+
},
|
|
14
|
+
"keywords": [
|
|
15
|
+
"astratra",
|
|
16
|
+
"saas",
|
|
17
|
+
"core"
|
|
18
|
+
],
|
|
19
|
+
"license": "MIT",
|
|
20
|
+
"publishConfig": {
|
|
21
|
+
"access": "public"
|
|
22
|
+
},
|
|
23
|
+
"peerDependencies": {
|
|
24
|
+
"express": ">=4"
|
|
25
|
+
},
|
|
26
|
+
"peerDependenciesMeta": {
|
|
27
|
+
"express": {
|
|
28
|
+
"optional": true
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
"dependencies": {
|
|
32
|
+
"express-validator": "7.3.2"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"jest": "30.4.2"
|
|
36
|
+
}
|
|
37
|
+
}
|
package/src/AppError.js
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
class AppError extends Error {
|
|
2
|
+
constructor(message, statusCode = 500) {
|
|
3
|
+
super(message);
|
|
4
|
+
this.name = this.constructor.name;
|
|
5
|
+
this.statusCode = statusCode;
|
|
6
|
+
this.isOperational = true;
|
|
7
|
+
|
|
8
|
+
Error.captureStackTrace(this, this.constructor);
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
module.exports = AppError;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
function apiResponse(res, statusCode, message, data = null, success = statusCode < 400) {
|
|
2
|
+
const payload = {
|
|
3
|
+
success,
|
|
4
|
+
message,
|
|
5
|
+
data,
|
|
6
|
+
timestamp: new Date().toISOString()
|
|
7
|
+
};
|
|
8
|
+
|
|
9
|
+
if (!success) {
|
|
10
|
+
payload.error = message;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
return res.status(statusCode).json(payload);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
module.exports = apiResponse;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
const apiResponse = require('./apiResponse');
|
|
2
|
+
|
|
3
|
+
function logError(err, req) {
|
|
4
|
+
if (process.env.NODE_ENV === 'test') {
|
|
5
|
+
return;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
const logger = (req && req.log) || console;
|
|
9
|
+
const log = typeof logger.error === 'function' ? logger.error.bind(logger) : console.error;
|
|
10
|
+
log(`[requestId=${(req && req.requestId) || 'n/a'}]`, err);
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
// Express only recognizes an error handler by arity (4 params) — `_next` must
|
|
14
|
+
// stay even though it's unused.
|
|
15
|
+
function errorMiddleware(err, req, res, _next) {
|
|
16
|
+
const statusCode = err.statusCode || err.status || 500;
|
|
17
|
+
const isServerError = statusCode >= 500;
|
|
18
|
+
const isProduction = process.env.NODE_ENV === 'production';
|
|
19
|
+
const message = isProduction && isServerError ? 'Internal server error' : err.message || 'Error';
|
|
20
|
+
const data = !isProduction && err.stack ? { stack: err.stack } : null;
|
|
21
|
+
|
|
22
|
+
if (isServerError) {
|
|
23
|
+
logError(err, req);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
return apiResponse(res, statusCode, message, data, false);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
module.exports = errorMiddleware;
|
package/src/index.d.ts
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
export interface JsonResponder {
|
|
2
|
+
json(payload: unknown): unknown;
|
|
3
|
+
}
|
|
4
|
+
|
|
5
|
+
export interface ResponseLike {
|
|
6
|
+
status(statusCode: number): JsonResponder;
|
|
7
|
+
setHeader?(name: string, value: string): unknown;
|
|
8
|
+
set?(name: string, value: string): unknown;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export interface RequestLike {
|
|
12
|
+
headers?: Record<string, string | undefined>;
|
|
13
|
+
log?: {
|
|
14
|
+
error?: (...args: unknown[]) => unknown;
|
|
15
|
+
};
|
|
16
|
+
originalUrl?: string;
|
|
17
|
+
requestId?: string;
|
|
18
|
+
url?: string;
|
|
19
|
+
[key: string]: unknown;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export type NextFunction = (error?: unknown) => unknown;
|
|
23
|
+
export type RequestHandler = (req: RequestLike, res: ResponseLike, next: NextFunction) => unknown;
|
|
24
|
+
export type ErrorRequestHandler = (err: Error & { status?: number; statusCode?: number }, req: RequestLike, res: ResponseLike, next: NextFunction) => unknown;
|
|
25
|
+
|
|
26
|
+
export interface ApiResponsePayload<T = unknown> {
|
|
27
|
+
success: boolean;
|
|
28
|
+
message: string;
|
|
29
|
+
data: T | null;
|
|
30
|
+
timestamp: string;
|
|
31
|
+
error?: string;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export function apiResponse<T = unknown>(
|
|
35
|
+
res: ResponseLike,
|
|
36
|
+
statusCode: number,
|
|
37
|
+
message: string,
|
|
38
|
+
data?: T | null,
|
|
39
|
+
success?: boolean
|
|
40
|
+
): unknown;
|
|
41
|
+
|
|
42
|
+
export function asyncHandler(fn: RequestHandler): RequestHandler;
|
|
43
|
+
|
|
44
|
+
export interface Logger {
|
|
45
|
+
info(message: string, meta?: unknown): void;
|
|
46
|
+
warn(message: string, meta?: unknown): void;
|
|
47
|
+
error(message: string, meta?: unknown): void;
|
|
48
|
+
debug(message: string, meta?: unknown): void;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function createLogger(serviceName?: string): Logger;
|
|
52
|
+
|
|
53
|
+
export class AppError extends Error {
|
|
54
|
+
statusCode: number;
|
|
55
|
+
isOperational: boolean;
|
|
56
|
+
constructor(message: string, statusCode?: number);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export const errorMiddleware: ErrorRequestHandler;
|
|
60
|
+
export function notFoundMiddleware(req: RequestLike, res: ResponseLike): unknown;
|
|
61
|
+
export const requestIdMiddleware: RequestHandler;
|
|
62
|
+
|
|
63
|
+
export interface ValidationLike {
|
|
64
|
+
run(req: RequestLike): unknown | Promise<unknown>;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export function validateMiddleware(validations?: ValidationLike[]): RequestHandler;
|
|
68
|
+
|
|
69
|
+
export type EnvDefault = string | number | boolean | null | undefined;
|
|
70
|
+
|
|
71
|
+
export interface EnvDefinition<TInput = string | EnvDefault, TOutput = TInput> {
|
|
72
|
+
default?: EnvDefault;
|
|
73
|
+
required?: boolean;
|
|
74
|
+
transform?: (value: TInput) => TOutput;
|
|
75
|
+
validate?: (value: TOutput) => boolean;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export type EnvSchema = Record<string, EnvDefault | EnvDefinition<any, any>>;
|
|
79
|
+
|
|
80
|
+
export type LoadEnvValue<T> =
|
|
81
|
+
T extends { transform: (...args: any[]) => infer R }
|
|
82
|
+
? R
|
|
83
|
+
: T extends { default: infer D }
|
|
84
|
+
? D | string | undefined
|
|
85
|
+
: T extends EnvDefault
|
|
86
|
+
? T | string | undefined
|
|
87
|
+
: string | undefined;
|
|
88
|
+
|
|
89
|
+
export type LoadedEnv<TSchema extends EnvSchema> = {
|
|
90
|
+
[K in keyof TSchema]: LoadEnvValue<TSchema[K]>;
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
export function loadEnv<TSchema extends EnvSchema = EnvSchema>(schema?: TSchema): LoadedEnv<TSchema>;
|
package/src/index.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
module.exports = {
|
|
2
|
+
apiResponse: require('./apiResponse'),
|
|
3
|
+
asyncHandler: require('./asyncHandler'),
|
|
4
|
+
createLogger: require('./logger'),
|
|
5
|
+
AppError: require('./AppError'),
|
|
6
|
+
errorMiddleware: require('./errorMiddleware'),
|
|
7
|
+
notFoundMiddleware: require('./notFoundMiddleware'),
|
|
8
|
+
requestIdMiddleware: require('./requestIdMiddleware'),
|
|
9
|
+
validateMiddleware: require('./validateMiddleware'),
|
|
10
|
+
loadEnv: require('./loadEnv')
|
|
11
|
+
};
|
package/src/loadEnv.js
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
const AppError = require('./AppError');
|
|
2
|
+
|
|
3
|
+
function hasValue(value) {
|
|
4
|
+
return value !== undefined && value !== null && value !== '';
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
function resolveValue(name, definition) {
|
|
8
|
+
const rawValue = process.env[name];
|
|
9
|
+
|
|
10
|
+
if (hasValue(rawValue)) {
|
|
11
|
+
return rawValue;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
if (Object.prototype.hasOwnProperty.call(definition, 'default')) {
|
|
15
|
+
return definition.default;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
if (definition.required) {
|
|
19
|
+
throw new AppError(`Missing required environment variable: ${name}`, 500);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
return undefined;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function normalizeDefinition(definition) {
|
|
26
|
+
if (definition && typeof definition === 'object' && !Array.isArray(definition)) {
|
|
27
|
+
return definition;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
return { default: definition };
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function loadEnv(schema = {}) {
|
|
34
|
+
return Object.entries(schema).reduce((config, [name, rawDefinition]) => {
|
|
35
|
+
const definition = normalizeDefinition(rawDefinition);
|
|
36
|
+
const value = resolveValue(name, definition);
|
|
37
|
+
|
|
38
|
+
if (value === undefined) {
|
|
39
|
+
config[name] = undefined;
|
|
40
|
+
return config;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const transformed = typeof definition.transform === 'function'
|
|
44
|
+
? definition.transform(value)
|
|
45
|
+
: value;
|
|
46
|
+
|
|
47
|
+
if (typeof definition.validate === 'function' && !definition.validate(transformed)) {
|
|
48
|
+
throw new AppError(`Invalid environment variable: ${name}`, 500);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
config[name] = transformed;
|
|
52
|
+
return config;
|
|
53
|
+
}, {});
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
module.exports = loadEnv;
|
package/src/logger.js
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
const levels = {
|
|
2
|
+
info: 'info',
|
|
3
|
+
warn: 'warn',
|
|
4
|
+
error: 'error',
|
|
5
|
+
debug: 'debug'
|
|
6
|
+
};
|
|
7
|
+
|
|
8
|
+
function writeLog(level, serviceName, message, meta) {
|
|
9
|
+
if (process.env.NODE_ENV === 'test') {
|
|
10
|
+
return;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
const timestamp = new Date().toISOString();
|
|
14
|
+
const line = `${timestamp} [${serviceName}] ${level.toUpperCase()}: ${message}`;
|
|
15
|
+
const writer = console[level] || console.log;
|
|
16
|
+
|
|
17
|
+
if (meta === undefined) {
|
|
18
|
+
writer(line);
|
|
19
|
+
return;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
writer(line, meta);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function createLogger(serviceName = 'app') {
|
|
26
|
+
return Object.keys(levels).reduce((logger, level) => {
|
|
27
|
+
logger[level] = (message, meta) => writeLog(level, serviceName, message, meta);
|
|
28
|
+
return logger;
|
|
29
|
+
}, {});
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
module.exports = createLogger;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
const { randomUUID } = require('crypto');
|
|
2
|
+
|
|
3
|
+
function getIncomingRequestId(req) {
|
|
4
|
+
if (!req || !req.headers) {
|
|
5
|
+
return null;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
return req.headers['x-request-id'] || req.headers['X-Request-Id'] || null;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
function requestIdMiddleware(req, res, next) {
|
|
12
|
+
const requestId = getIncomingRequestId(req) || randomUUID();
|
|
13
|
+
req.requestId = requestId;
|
|
14
|
+
|
|
15
|
+
if (typeof res.setHeader === 'function') {
|
|
16
|
+
res.setHeader('X-Request-Id', requestId);
|
|
17
|
+
} else if (typeof res.set === 'function') {
|
|
18
|
+
res.set('X-Request-Id', requestId);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
return next();
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
module.exports = requestIdMiddleware;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
const { validationResult } = require('express-validator');
|
|
2
|
+
const apiResponse = require('./apiResponse');
|
|
3
|
+
|
|
4
|
+
function validateMiddleware(validations = []) {
|
|
5
|
+
return async function validateRequest(req, res, next) {
|
|
6
|
+
for (const validation of validations) {
|
|
7
|
+
await validation.run(req);
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
const result = validationResult(req);
|
|
11
|
+
|
|
12
|
+
if (result.isEmpty()) {
|
|
13
|
+
return next();
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
return apiResponse(res, 400, 'Validation failed', { errors: result.array() }, false);
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
module.exports = validateMiddleware;
|