@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 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
+ }
@@ -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,7 @@
1
+ function asyncHandler(fn) {
2
+ return function wrappedAsyncHandler(req, res, next) {
3
+ return Promise.resolve(fn(req, res, next)).catch(next);
4
+ };
5
+ }
6
+
7
+ module.exports = asyncHandler;
@@ -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,7 @@
1
+ const apiResponse = require('./apiResponse');
2
+
3
+ function notFoundMiddleware(req, res) {
4
+ return apiResponse(res, 404, 'Route not found', { path: req.originalUrl || req.url }, false);
5
+ }
6
+
7
+ module.exports = notFoundMiddleware;
@@ -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;