Skip to content

Commit 557da99

Browse files
eli-sterlingeli-sterling
committed
first commit
0 parents  commit 557da99

File tree

13 files changed

+5290
-0
lines changed

13 files changed

+5290
-0
lines changed

‎.github/workflows/nodejs.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Node.js CI
2+
3+
on:
4+
push:
5+
tags:
6+
- '*'
7+
8+
permissions:
9+
id-token: write
10+
contents: read
11+
12+
jobs:
13+
build:
14+
runs-on: ubuntu-latest
15+
strategy:
16+
matrix:
17+
node-version: [22.x]
18+
steps:
19+
- uses: actions/checkout@v4
20+
- name: Use Node.js ${{ matrix.node-version }}
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: ${{ matrix.node-version }}
24+
- run: npm ci
25+
- run: npm test
26+
- name: Configure npm auth token
27+
run: npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}
28+
- name: Publish to npm
29+
run: npm publish --access public --provenance
30+
env:
31+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
lerna-debug.log*
8+
.pnpm-debug.log*
9+
10+
# Diagnostic reports (https://nodejs.org/api/report.html)
11+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
12+
13+
# Runtime data
14+
pids
15+
*.pid
16+
*.seed
17+
*.pid.lock
18+
19+
# Directory for instrumented libs generated by jscoverage/JSCover
20+
lib-cov
21+
22+
# Coverage directory used by tools like istanbul
23+
coverage
24+
*.lcov
25+
26+
# nyc test coverage
27+
.nyc_output
28+
29+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
30+
.grunt
31+
32+
# Bower dependency directory (https://bower.io/)
33+
bower_components
34+
35+
# node-waf configuration
36+
.lock-wscript
37+
38+
# Compiled binary addons (https://nodejs.org/api/addons.html)
39+
build/Release
40+
41+
# Dependency directories
42+
node_modules/
43+
jspm_packages/
44+
45+
# Snowpack dependency directory (https://snowpack.dev/)
46+
web_modules/
47+
48+
# TypeScript cache
49+
*.tsbuildinfo
50+
51+
# Optional npm cache directory
52+
.npm
53+
54+
# Optional eslint cache
55+
.eslintcache
56+
57+
# Optional stylelint cache
58+
.stylelintcache
59+
60+
# Microbundle cache
61+
.rpt2_cache/
62+
.rts2_cache_cjs/
63+
.rts2_cache_es/
64+
.rts2_cache_umd/
65+
66+
# Optional REPL history
67+
.node_repl_history
68+
69+
# Output of 'npm pack'
70+
*.tgz
71+
72+
# Yarn Integrity file
73+
.yarn-integrity
74+
75+
# dotenv environment variable files
76+
.env
77+
.env.development.local
78+
.env.test.local
79+
.env.production.local
80+
.env.local
81+
82+
# parcel-bundler cache (https://parceljs.org/)
83+
.cache
84+
.parcel-cache
85+
86+
# Next.js build output
87+
.next
88+
out
89+
90+
# Nuxt.js build / generate output
91+
.nuxt
92+
dist
93+
94+
# Gatsby files
95+
.cache/
96+
# Comment in the public line in if your project uses Gatsby and not Next.js
97+
# https://nextjs.org/blog/next-9-1#public-directory-support
98+
# public
99+
100+
# vuepress build output
101+
.vuepress/dist
102+
103+
# vuepress v2.x temp and cache directory
104+
.temp
105+
.cache
106+
107+
# vitepress build output
108+
**/.vitepress/dist
109+
110+
# vitepress cache directory
111+
**/.vitepress/cache
112+
113+
# Docusaurus cache and generated files
114+
.docusaurus
115+
116+
# Serverless directories
117+
.serverless/
118+
119+
# FuseBox cache
120+
.fusebox/
121+
122+
# DynamoDB Local files
123+
.dynamodb/
124+
125+
# TernJS port file
126+
.tern-port
127+
128+
# Stores VSCode versions used for testing VSCode extensions
129+
.vscode-test
130+
131+
# yarn v2
132+
.yarn/cache
133+
.yarn/unplugged
134+
.yarn/build-state.yml
135+
.yarn/install-state.gz
136+
.pnp.*
137+
138+
# jest
139+
.jest.result

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# MIT License
2+
3+
Copyright (c) 2025 Eli Sterling, eliware.org
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.

‎README.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# [![eliware.org](https://eliware.org/logos/brand.png)](https://discord.gg/M6aTR9eTwN)
2+
3+
## @eliware/common [![npm version](https://img.shields.io/npm/v/@eliware/common.svg)](https://www.npmjs.com/package/@eliware/common) [![license](https://img.shields.io/github/license/eliware/common.svg)](LICENSE) [![build status](https://github.com/eliware/common/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eliware/common/actions)
4+
5+
> An ESM/Jest/Node-friendly utility for resolving file and directory paths, logging, error handling, and signal handling in both CommonJS and ESM environments.
6+
7+
---
8+
9+
## Table of Contents
10+
11+
- [Features](#features)
12+
- [Installation](#installation)
13+
- [Usage](#usage)
14+
- [ESM Example](#esm-example)
15+
- [CommonJS Example](#commonjs-example)
16+
- [API](#api)
17+
- [TypeScript](#typescript)
18+
- [License](#license)
19+
20+
## Features
21+
22+
- Unified API for CommonJS and ESM
23+
- Logging with [@eliware/log]
24+
- Path utilities with [@eliware/path]
25+
- Error handler registration with [@eliware/errors]
26+
- Signal/shutdown handler registration with [@eliware/signals]
27+
- **Re-exports Node.js built-in `fs` module**
28+
- TypeScript type definitions included
29+
- Fully tested with Jest
30+
31+
## Installation
32+
33+
```bash
34+
npm install @eliware/common
35+
```
36+
37+
## Usage
38+
39+
### ESM Example
40+
41+
```js
42+
import { fs, log, path, pathUrl, getCurrentDirname, getCurrentFilename, registerHandlers, registerSignals } from '@eliware/common';
43+
44+
log.info('This is an info log from @eliware/log');
45+
46+
const { removeHandlers } = registerHandlers();
47+
log.info('Registered error handlers.');
48+
49+
const envFile = path(import.meta, '.env');
50+
log.info(`path to env file: ${envFile}`);
51+
52+
const envFileUrl = pathUrl(import.meta, '.env');
53+
log.info(`pathUrl to env file: ${envFileUrl}`);
54+
55+
const { shutdown } = registerSignals();
56+
log.info('Registered signal handlers.');
57+
58+
// Example usage of fs
59+
const files = fs.readdirSync(getCurrentDirname(import.meta));
60+
log.info(`Files in current directory: ${files.join(', ')}`);
61+
```
62+
63+
### CommonJS Example
64+
65+
```js
66+
const { fs, log, path, pathUrl, getCurrentDirname, getCurrentFilename, registerHandlers, registerSignals } = require('@eliware/common');
67+
68+
log.info('This is an info log from @eliware/log');
69+
70+
const { removeHandlers } = registerHandlers();
71+
log.info('Registered error handlers.');
72+
73+
const envFile = path(__dirname, '.env');
74+
log.info(`path to env file: ${envFile}`);
75+
76+
const envFileUrl = pathUrl(__dirname, '.env');
77+
log.info(`pathUrl to env file: ${envFileUrl}`);
78+
79+
const { shutdown } = registerSignals();
80+
log.info('Registered signal handlers.');
81+
82+
// Example usage of fs
83+
const files = fs.readdirSync(getCurrentDirname(__dirname));
84+
log.info(`Files in current directory: ${files.join(', ')}`);
85+
```
86+
87+
## API
88+
89+
### fs
90+
91+
Re-export of the Node.js built-in [`fs`](https://nodejs.org/api/fs.html) module. Use for file system operations.
92+
93+
### log
94+
95+
Default logger instance from [@eliware/log]. Supports `.info`, `.warn`, `.error`, etc.
96+
97+
### path(metaOrDir, ...segments)
98+
99+
Joins the current dirname with provided segments to form an absolute path.
100+
101+
- `metaOrDir`: `import.meta` (ESM), a string (dirname, e.g. `__dirname`), or undefined
102+
- `segments`: Path segments to join
103+
- Returns: Absolute path string
104+
105+
### getCurrentDirname(metaOrDir, dirnameFn?)
106+
107+
Returns the current directory name.
108+
109+
- `metaOrDir`: `import.meta` (ESM), a string (dirname, e.g. `__dirname`), or undefined
110+
- `dirnameFn`: Optional custom dirname function
111+
- Returns: Absolute path to the current directory
112+
113+
### getCurrentFilename(metaOrDir)
114+
115+
Returns the current filename.
116+
117+
- `metaOrDir`: `import.meta` (ESM), a string (dirname, e.g. `__dirname`), or undefined
118+
- Returns: Absolute path to the current file
119+
120+
### registerHandlers(processObj?, logger?)
121+
122+
Registers process-level exception handlers for uncaught exceptions, unhandled rejections, warnings, and exit events.
123+
124+
- `processObj`: The process object to attach handlers to (default: process)
125+
- `logger`: Logger for output (default: log)
126+
- Returns: `{ removeHandlers }` function to remove all registered handlers
127+
128+
### registerSignals(options?)
129+
130+
Sets up shutdown handlers for the process.
131+
132+
- `options`: `{ processObj, logger, signals }`
133+
- Returns: `{ shutdown, getShuttingDown }`
134+
135+
## TypeScript
136+
137+
Type definitions are included and exported for all main functions and options:
138+
139+
```ts
140+
import { fs, log, path, getCurrentDirname, getCurrentFilename, registerHandlers, registerSignals, RegisterSignalsOptions } from '@eliware/common';
141+
```
142+
143+
## Support
144+
145+
For help, questions, or to chat with the author and community, visit:
146+
147+
[![Discord](https://eliware.org/logos/discord_96.png)](https://discord.gg/M6aTR9eTwN)[![eliware.org](https://eliware.org/logos/eliware_96.png)](https://discord.gg/M6aTR9eTwN)
148+
149+
**[eliware.org on Discord](https://discord.gg/M6aTR9eTwN)**
150+
151+
## License
152+
153+
[MIT © 2025 Eli Sterling, eliware.org](LICENSE)
154+
155+
## Links
156+
157+
- [Home Page](https://eliware.org)
158+
- [GitHub](https://github.com/eliware/common)
159+
- [npm](https://www.npmjs.com/package/@eliware/common)
160+
- [Discord](https://discord.gg/M6aTR9eTwN)

‎example.cjs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Example usage of the common package in CommonJS
2+
const { log, path, pathUrl, registerHandlers, registerSignals } = require('@eliware/common');
3+
4+
log.info('This is an info log from @eliware/log');
5+
6+
const { removeHandlers } = registerHandlers();
7+
log.info('Registered error handlers.');
8+
9+
const envFile = path(__dirname, '.env');
10+
log.info(`path to env file: ${envFile}`);
11+
12+
const envFileUrl = pathUrl(__dirname, '.env');
13+
log.info(`pathUrl to env file: ${envFileUrl}`);
14+
15+
const { shutdown } = registerSignals();
16+
log.info('Registered signal handlers.');

‎example.mjs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Example usage of the common package in ESM
2+
import { log, path, pathUrl, registerHandlers, registerSignals } from '@eliware/common';
3+
4+
log.info('This is an info log from @eliware/log');
5+
6+
const { removeHandlers } = registerHandlers();
7+
log.info('Registered error handlers.');
8+
9+
const envFile = path(import.meta, '.env');
10+
log.info(`path to env file: ${envFile}`);
11+
12+
const envFileUrl = pathUrl(import.meta, '.env');
13+
log.info(`pathUrl to env file: ${envFileUrl}`);
14+
15+
const { shutdown } = registerSignals();
16+
log.info('Registered signal handlers.');

0 commit comments

Comments
 (0)