elseware-js
v3.4.1
Published
A modern JavaScript and Node.js utility framework powering the elseware Technology ecosystem.
Readme
elseware-js
A modern Node.js utility and application framework powering the elseware ecosystem.
elseware-js provides a collection of reusable components, utilities, middleware, abstractions, and development patterns for building scalable Node.js applications and microservices.
Features
- TypeScript-first development
- Express.js integration
- Repository pattern abstractions
- Service layer architecture
- Request context management
- Structured error handling
- Validation utilities
- Logging and observability support
- Microservice-friendly design
- Reusable application building blocks
Installation
npm install elseware-jsUsage
import { AppError } from "elseware-js";
throw new AppError("Something went wrong");The root package exports the complete public API. Internally, feature folders use barrel exports to keep that API organized without requiring consumers to know the source directory structure.
import {
AzureBlobStorageService,
CloudflareR2StorageService,
type ILogger,
Logger,
appendUrlPath,
formatBytes,
sha256File,
verifyFileIntegrity,
} from "elseware-js";CloudflareR2StorageService uses the R2 S3 endpoint and supports transparent
key prefixes, conditional/immutable writes, multipart uploads, metadata,
pagination, and presigned private downloads. Supplying an explicit endpoint
and forcePathStyle also supports MinIO for local integration tests. The Azure
service remains available for existing consumers.
Express is an optional peer and must be installed explicitly when using the HTTP features. Mongoose is a runtime dependency because the root package exports MongoDB providers and must remain safe to load in every consumer.
Composable transactional email
Version 3 exports ComposableEmailRequestSchema,
EmailTemplateSchemaV1Schema, EmailBlockSchema, their inferred TypeScript
types, and the matching response contract. The schema supports a bounded set
of declarative blocks and escaped simple bindings only; helpers, partials,
conditionals, raw HTML, triple braces, and unresolved bindings are rejected.
Email delivery uses the generic EmailDeliveryProvider contract. SMTP and
Resend are built in and selected once at startup with createEmailProvider:
const provider = createEmailProvider({
type: "resend",
config: { apiKey: process.env.RESEND_API_KEY! },
});
await provider.send({
from: "[email protected]",
to: "[email protected]",
subject: "Welcome",
html: "<p>Welcome</p>",
text: "Welcome",
idempotencyKey: crypto.randomUUID(),
});Provider-specific configuration stays with the consuming application. Custom
providers implement EmailDeliveryProvider and may expose their own typed
EmailProviderFactory<TConfig>. Delivery performs no retries or provider
failover.
OpenTelemetry
Backend services can call initializeTelemetry before importing their
application modules. The shared environment contract supplies safe defaults
for service identity, OTLP/HTTP protobuf, timeout, and parent-based sampling;
OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are optional
deployment secrets. Exporter failures are fail-open.
import { initializeTelemetry, observabilityEnvSchema } from "elseware-js";
const config = observabilityEnvSchema.parse(process.env);
const telemetry = initializeTelemetry(config);
// Import and start Express after telemetry is initialized.
await telemetry.shutdown();createTelemetryMiddleware adds the active trace ID to responses and annotates
the existing request context. Automatic instrumentation covers HTTP, Express,
MongoDB, and ioredis when an OTLP endpoint is configured.
Source conventions
- Classes, interfaces, types, and enums use PascalCase filenames matching the primary export.
- Standalone functions use camelCase filenames matching the primary function.
- Cohesive collections use lowercase role names such as
types.tsandutils.ts; role suffixes such as.service.tsare not used. - Implementation files import concrete modules directly.
index.tsbarrels define public feature boundaries and use explicit value and type exports. - Existing public acronym names such as
EJS,DTOConfig, andJWTServiceremain naming compatibility exceptions.
Development
TypeScript 7 is the only compiler dependency. tsup builds the JavaScript
bundles, then the TypeScript 7 CLI emits the declaration files. Oxlint provides
TypeScript and Vitest linting without relying on the removed legacy compiler
API.
npm ci
npm run validateAutomated npm publishing
Pull requests targeting main run the complete validation suite and verify
that the package version has not already been published. A successful merge to
main runs the same checks and publishes through GitHub's OIDC trusted
publishing; no long-lived npm token is stored in GitHub. Because this source
repository is private, the workflow disables npm provenance, which npm only
accepts for public source repositories.
Before enabling the workflow, configure npm's trusted publisher for the
elseware-js package with the GitHub organization/repository and the workflow
filename .github/workflows/publish.yml. Create the npm-production GitHub
environment and restrict it to the main branch. Keep the package version in
package.json and package-lock.json synchronized; bump it in the release PR,
for example:
npm version patch --no-git-tag-versionThe workflow deliberately fails before publishing if that exact version is
already present in the npm registry. This prevents accidental republishing and
ensures every merge that publishes a package has an explicit version change.
If the repository is later made public, remove --provenance=false from the
publish workflow to enable signed npm provenance attestations.
Useful commands:
npm run typecheck— TypeScript 7 validationnpm run lint/npm run lint:fix— Oxlint checks and fixesnpm run format:check/npm run format— Prettier checks and formattingnpm run deadcode— unused files, exports, and dependency checksnpm run test:run— the complete self-contained Vitest suitenpm run test:coverage— tests with enforced coverage thresholdsnpm run build— ESM and declaration bundles
Documentation
Documentation, guides, and usage examples are available in the official repository.
About elseware Technology
elseware Technology builds tools, frameworks, and solutions for software engineering, cloud computing, game development, and developer productivity.
Contributing
Contributions, issues, and feature requests are welcome.
License
This project is licensed under the MIT License.
Copyright © 2026 elseware Technology.
