@leostacowski/pkgs 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @leostacowski/pkgs
+
+_"It's ugly but it's mine."_
+
+\- _Me describing my code._
+
+## Table of Contents
+
+- [Motivation](#motivation)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Modules](#modules)
+  - [@leostacowski/pkgs/logger](#leostacowskipkgslogger)
+
+## Motivation
+
+After repeatedly starting things from scratch for a long time:
+
+```text
+I decided to finally create a centralized repo for my scripts.
+```
+
+This decision was directly inspired by Eskil Steenberg's talk: "_[You should finish your software](https://youtu.be/EGLoKbBn-VI?si=uFVlbKIcRolcOzCy)_".
+
+If you are using any of these modules and something is breaking, or if you have a suggestion, please [open an issue](https://github.com/leostacowski/pkgs/issues/).
+
+I intend to keep adding stuff to this repo as long as I continue to reinvent the wheel!
+
+## Requirements
+
+`node >= 22.12.0` is a _safe choice_, but let me know your luck on older releases.
+
+## Installation
+
+```bash
+npm i @leostacowski/pkgs
+```
+
+## Usage
+
+Everything begins at the `@leostacowski/pkgs` package:
+
+```js
+import pkgs from '@leostacowski/pkgs'
+// or
+const pkgs = require('@leostacowski/pkgs').default
+```
+
+Then import what you need:
+
+```js
+import { ModuleX } from '@leostacowski/pkgs'
+// or
+const { ModuleX } = require('@leostacowski/pkgs')
+```
+
+Or import a specific module and ignore the rest:
+
+```js
+import ModuleY from '@leostacowski/pkgs/ModuleY'
+// or
+const ModuleY = require('@leostacowski/pkgs/ModuleY')
+```
+
+For usage details on each module, refer to [Modules](#modules).
+
+## Modules
+
+### @leostacowski/pkgs/logger
+
+A simple logger that supports aliases, types, colors and other knobs.
+
+Check its [README.md](https://github.com/leostacowski/pkgs/blob/main/modules/logger/README.md) for details.

package/modules/index.js

@@ -0,0 +1,7 @@
+import LoggerModule from './logger/index.js'
+
+export const Logger = LoggerModule
+
+export default {
+  Logger,
+}

package/modules/logger/README.md

@@ -0,0 +1,240 @@
+# @leostacowski/pkgs/logger
+
+Simple Logger that supports aliases, types, colors and other knobs.
+
+> For the main package `@leostacowski/pkgs`: See the [main README.md](/README.md).
+
+# Table of Contents
+
+- [Usage](#usage)
+  - [Import](#import)
+  - [Options](#options)
+    - [_prefix_: `string`](#prefix-string)
+    - [_group_: `boolean`](#group-boolean)
+    - [_colors_: `boolean`](#colors-boolean)
+    - [_text_color_: `string`](#text_color-string)
+    - [_level_: `number`](#level-number)
+  - [Types](#types)
+  - [Examples](#examples)
+    - [Basic](#basic)
+    - [Prefix](#prefix)
+    - [Same Line](#same-line)
+    - [Level Filtering](#level-filtering)
+
+# Usage
+
+## Import
+
+From `@leostacowski/pkgs`:
+
+```js
+import { Logger } from '@leostacowski/pkgs'
+// or
+const { Logger } = require('@leostacowski/pkgs')
+```
+
+Or straight from the source:
+
+```js
+import Logger from '@leostacowski/pkgs/logger'
+// or
+const Logger = require('@leostacowski/pkgs/logger')
+```
+
+## Options
+
+When calling `Logger()`, you can customize your instance. Here are the defaults:
+
+```js
+const logger = Logger({
+  prefix: '',
+  group: true,
+  colors: true,
+  text_color: '',
+  level: 0,
+})
+```
+
+Alternatively, pass a single `string` argument, and set just `prefix`:
+
+```js
+const logger = Logger('My prefix 😉')
+```
+
+You could just ignore everything:
+
+```js
+const logger = Logger()
+```
+
+### _prefix_: `string`
+
+Defines a value to append to the output prefix.
+
+### _group_: `boolean`
+
+Toggles the use of [group](https://nodejs.org/api/console.html#consolegrouplabel) and [groupEnd](https://nodejs.org/api/console.html#consolegroupend).
+
+If `true`, uses [_prefix_](#prefix-string) as the group label.
+
+### _colors_: `boolean`
+
+Toggles the use of [ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code) on console output. Here are the defaults:
+
+```js
+{
+  RED: {
+    code: '\x1b[91m',
+  },
+  GREEN: {
+    code: '\x1b[92m',
+  },
+  YELLOW: {
+    code: '\x1b[93m',
+  },
+  DEFAULT: {
+    code: '\x1b[94m',
+  },
+  RESET: {
+    code: '\x1b[0m',
+  },
+}
+```
+
+### _text_color_: `string`
+
+Specify your own ANSI color code for console output text.
+
+If [colors](#colors-boolean) is `false`, this option is ignored.
+
+### _level_: `number`
+
+One of:
+
+- `0`: Allows [ `DEBUG`, `SUCCESS`, `WARNING`, `ERROR` ]
+- `1`: Allows [ `WARNING`, `ERROR` ]
+- `2`: Allows [ `ERROR` ]
+
+## Types
+
+The logger supports four types of output:
+
+- **DEBUG**;
+- **SUCCESS**;
+- **WARNING**;
+- **ERROR**.
+
+Each level is aliased to support multiple ways of being emitted:
+
+- **DEBUG**:
+  - `log`;
+  - `info`;
+  - `debug`;
+  - `l`;
+  - `i`;
+  - `d`.
+- **SUCCESS**:
+  - `success`;
+  - `s`.
+- **WARNING**:
+  - `warning`;
+  - `warn`;
+  - `w`.
+- **ERROR**:
+  - `error`;
+  - `err`;
+  - `e`.
+
+This means that all of this is game:
+
+```js
+logger.log('"log" emits DEBUG')
+logger.info('"info" emits DEBUG')
+logger.debug('"debug" emits DEBUG')
+logger.l('"l" emits DEBUG')
+logger.i('"i" emits DEBUG')
+logger.d('"d" emits DEBUG')
+logger.success('"success" emits SUCESS')
+logger.s('"s" emits SUCESS')
+logger.warning('"warning" emits WARNING')
+logger.warn('"warn" emits WARNING')
+logger.w('"w" emits WARNING')
+logger.error('"error" emits ERROR')
+logger.err('"err" emits ERROR')
+logger.e('"e" emits ERROR')
+```
+
+## Examples
+
+### Basic
+
+```js
+import Logger from '@leostacowski/pkgs/logger'
+
+const logger = Logger()
+
+logger.log('Hello World!')
+```
+
+Outputs:
+
+```bash
+ > [2026-11-07T04:30:28.965Z] DEBUG:
+  Hello World!
+```
+
+### Prefix
+
+```js
+import Logger from '@leostacowski/pkgs/logger'
+
+const logger = Logger('Hello')
+
+logger.warn('World!')
+```
+
+Outputs:
+
+```bash
+ > [2026-11-07T05:23:15.708Z] WARNING Hello:
+  World!
+```
+
+### Same Line
+
+```js
+import Logger from '@leostacowski/pkgs/logger'
+
+const logger = Logger({
+  group: false,
+})
+
+logger.info('Hello World!')
+```
+
+Outputs:
+
+```bash
+ > [2026-11-07T05:25:23.193Z] DEBUG: Hello World!
+```
+
+### Level Filtering
+
+```js
+import Logger from '@leostacowski/pkgs/logger'
+
+const logger = Logger({
+  level: 2,
+})
+
+logger.log('0')
+logger.warn('1')
+logger.error('2')
+```
+
+Outputs:
+
+```bash
+ > [2026-11-07T05:30:44.055Z] ERROR:
+  2
+```

package/modules/logger/index.js

@@ -0,0 +1,152 @@
+const LOGGER_COLORS = {
+  RED: {
+    code: '\x1b[91m',
+  },
+  GREEN: {
+    code: '\x1b[92m',
+  },
+  YELLOW: {
+    code: '\x1b[93m',
+  },
+  DEFAULT: {
+    code: '\x1b[94m',
+  },
+  RESET: {
+    code: '\x1b[0m',
+  },
+}
+
+const LOGGER_TYPES = [
+  {
+    level: 2,
+    prefix: 'ERROR',
+    emitter: console.error,
+    color: LOGGER_COLORS.RED,
+    aliases: ['error', 'err', 'e'],
+  },
+  {
+    level: 1,
+    prefix: 'WARNING',
+    emitter: console.warn,
+    color: LOGGER_COLORS.YELLOW,
+    aliases: ['warning', 'warn', 'w'],
+  },
+  {
+    level: 0,
+    prefix: 'SUCCESS',
+    emitter: console.log,
+    color: LOGGER_COLORS.GREEN,
+    aliases: ['success', 's'],
+  },
+  {
+    level: 0,
+    prefix: 'DEBUG',
+    emitter: console.log,
+    color: LOGGER_COLORS.DEFAULT,
+    aliases: ['log', 'info', 'debug', 'l', 'i', 'd'],
+  },
+]
+
+const BASE_OPTS = {
+  prefix: '',
+  group: true,
+  colors: true,
+  text_color: '',
+  level: 0,
+}
+
+function emit(content = [], opts = {}, logger_type = {}) {
+  if (opts?.level > logger_type.level) return
+  if (!content.length) return
+
+  const prefix = (() => {
+    const target = []
+
+    target.push(`> [${new Date().toISOString()}] ${logger_type.prefix}`)
+
+    if (opts?.prefix) {
+      target.push(opts.prefix)
+    }
+
+    target[target.length - 1] = `${target[target.length - 1]}:`
+
+    if (opts?.colors) {
+      target.unshift(logger_type.color.code)
+      target.push(LOGGER_COLORS.RESET.code)
+    }
+
+    return target.join(' ')
+  })()
+
+  const message = (() => {
+    const target = []
+    let text_color = ''
+
+    for (const item of content) {
+      target.push(typeof item === 'string' ? item : JSON.stringify(item))
+    }
+
+    if (opts?.colors && opts?.text_color) {
+      text_color = opts.text_color
+    }
+
+    if (text_color) {
+      return `${text_color}${target.join()}${LOGGER_COLORS.RESET.code}`
+    }
+
+    return target.join(' ')
+  })()
+
+  if (opts.group) {
+    console.group(prefix)
+    logger_type.emitter(message)
+    console.groupEnd()
+  } else {
+    logger_type.emitter(prefix, message)
+  }
+
+  return
+}
+
+function get_emitters(args) {
+  const opts = {}
+
+  Object.keys(BASE_OPTS).forEach((key) => {
+    if (typeof args?.[key] === typeof BASE_OPTS[key]) {
+      opts[key] = args[key]
+    } else {
+      opts[key] = BASE_OPTS[key]
+    }
+  })
+
+  const target = {}
+
+  for (const logger_type of LOGGER_TYPES) {
+    for (const alias of logger_type.aliases) {
+      target[alias] = function () {
+        return emit(Array.from(arguments), opts, logger_type)
+      }
+    }
+  }
+
+  return target
+}
+
+const Logger = function (args) {
+  if (typeof args === 'string') {
+    args = {
+      prefix: args,
+    }
+  }
+
+  const emitters = get_emitters(args)
+  const methods = {}
+
+  for (const emitter of Object.keys(emitters)) {
+    methods[emitter] = emitters[emitter]
+  }
+
+  return methods
+}
+
+export default Logger

package/package.json

@@ -1,6 +1,45 @@
-{
-  "name": "@leostacowski/pkgs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@leostacowski/pkgs",
+  "version": "0.0.1",
+  "description": "Centralized package of reusable JavaScript tools.",
+  "homepage": "https://www.npmjs.com/package/@leostacowski/pkgs",
+  "keywords": [
+    "nodejs",
+    "javascript",
+    "npm"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bugs": {
+    "url": "https://github.com/leostacowski/pkgs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leostacowski/pkgs.git"
+  },
+  "license": "Unlicense",
+  "author": {
+    "name": "leostacowski",
+    "email": "leonardo.stacowski@hotmail.com",
+    "url": "git+https://github.com/leostacowski/"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "modules"
+  ],
+  "exports": {
+    ".": "./modules/index.js",
+    "./logger": "./modules/logger/index.js"
+  },
+  "imports": {
+    "#logger/*": "./modules/logger/*"
+  },
+  "scripts": {
+    "dev": "node --watch ./modules/index.js",
+    "deploy": "npm publish"
+  }
+}