@fullstackunicorn/initialize 1.0.2 → 1.0.6

package/index.js

@@ -4,10 +4,13 @@ String.prototype.low = function () { return this.toLowerCase() }
 String.prototype.cut = function (n = 1) { return this.slice(0, -n) }
 
 class F3Error extends Error {
-    constructor(service, message, params = {}) {
+    constructor(service, message, params, cause) {
         super(message)
+        this.name = 'F3Error'
         this.service = service
-        this.params = params
+        if (params) this.params = params
+        if (cause) this.cause = cause
+        if (Error.captureStackTrace) Error.captureStackTrace(this, F3Error)
     }
 }
 
@@ -15,6 +18,7 @@ globalThis.F3 = {}
 
 globalThis.F3.service = ''
 
+globalThis.F3.isErr = value => value instanceof Error
 globalThis.F3.isArr = value => Array.isArray(value)
 globalThis.F3.isNil = value => value === undefined || value === null
 globalThis.F3.isFnc = value => typeof value === 'function'
@@ -42,7 +46,7 @@ globalThis.F3.obj.isGood = obj => !!obj && typeof obj === 'object' && Object.key
 globalThis.F3.obj.safe = obj => (typeof obj === 'object' && obj !== null) ? obj : {}
 globalThis.F3.obj.isPlain = obj => obj !== null && typeof obj === 'object' && Object.getPrototypeOf(obj) === Object.prototype
 globalThis.F3.obj.inKb = obj => new TextEncoder().encode(JSON.stringify(obj)).length / 1000
-globalThis.F3.obj.string = obj => {
+globalThis.F3.obj.toStr = obj => {
     if (typeof obj === 'string') return obj
     try { return JSON.stringify(obj, null, 2) } catch { return String(obj) }
 }
@@ -90,25 +94,41 @@ globalThis.F3.log.obj = (object = {}, ...rest) => {
     const result = []
     for (const item of rest) result.push(String(item))
     for (const key of Object.keys(object)) {
-        try { result.push(`\n${key}:\n${F3.obj.string(object[key])}\n`) }
+        try { result.push(`\n${key}:\n${F3.obj.toStr(object[key])}\n`) }
         catch { result.push(`\n${key}: [Error serializing value]\n`) }
     }
     console.log(result.join('\n'))
 }
 
+globalThis.F3.throw = (...args) => { throw new F3Error(F3.service, ...args) }
+
 globalThis.F3.err = {}
 globalThis.F3.err.is500 = status => !!status && status >= 500
 globalThis.F3.err.is400 = status => !!status && status >= 400 && status < 500
 
+globalThis.F3.err.toObj = err => { 
+    const base = { name:err.name, message:err.message, stack:err.stack }
+    try { return Object.assign(base, Object.fromEntries(Object.entries(err)))} 
+    catch { return base }
+}
+globalThis.F3.err.toStr = err => {
+    if (F3.isErr(err)) return F3.obj.toStr(F3.err.toObj(err))
+    if (F3.isObj(err)) return F3.obj.toStr(err)
+    if (F3.isStr(err)) return err
+    return String(err)
+}
+globalThis.F3.err.logs = err => {
+    if (err instanceof F3Error) console.error(F3.obj.toStr(err))
+    else console.error('non-F3-error',F3.obj.toStr(err))
+}
+
 globalThis.F3.catch = {}
-globalThis.F3.catch.throw = (error, ...rest) => { 
-    if (rest.length > 0) console.log(...rest)
-    throw error
- }
+globalThis.F3.catch.throw = (error, message) => {
+    if (error instanceof F3Error) throw error
+    F3.throw(message, null, F3.err.toStr(error))
+}
 globalThis.F3.catch.log = (...args) => console.log(...args)
-globalThis.F3.catch.res = (first, ...rest) => {
-    if (rest.length > 0) console.log(...rest)
+globalThis.F3.catch.res = (first, error) => {
+    if (error) F3.err.logs(error)
     return first
-}
-
-globalThis.F3.throw = (message, params) => { throw new F3Error(F3.service, message, params) }
+}

package/package.json

@@ -1,19 +1,20 @@
 {
-    "version": "1.0.2",
+    "version": "1.0.6",
     "name": "@fullstackunicorn/initialize",
     "author": "lucanigido (https://fullstackunicorn.dev/author/lucanigido)",
     "description": "A collection of global utility functions for JavaScript/Node.js projects (type checks, string helpers, logging, etc.). Side-effect import extends globals.",
-    "readme": "README.md",
-    "main": "index.js",
-    "type": "module",
     "license": "MIT",
+    "type": "module",
+    "private": false,
+    "readme": "package.readme.md",
+    "main": "index.js",
+    "files": [
+        "index.js"
+    ],
     "repository": {
         "type": "git",
         "url": "https://gitlab.com/fullstackunicorn/initialize.git"
     },
-    "files": [
-        "index.js"
-    ],
     "sideEffects": [
         "index.js"
     ],
@@ -31,6 +32,7 @@
         "#@/*": "./*"
     },
     "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
+        "test": "exit 1",
+        "cli": "chmod +x ./config.cli.sh && ./config.cli.sh"
     }
 }

package/readme.md

@@ -1,190 +0,0 @@
-# @fullstackunicorn/initialize
-
-[![NPM version](https://badge.fury.io/js/%40fullstackunicorn%2Finitialize.svg)](https://www.npmjs.com/package/@fullstackunicorn/initialize)
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node.js Version](https://img.shields.io/badge/node-v20-green.svg)](https://nodejs.org/)
-
-A lightweight, zero-dependency utility library for JavaScript/Node.js. It extends global objects with handy helpers: String prototype methods for quick transformations and a `F3` namespace for type checks, safe accessors, logging, templating, and error handling. Designed as a side-effect module—just import once at the top of your project to make everything globally available.
-
-Ideal for scripts, apps, or teams wanting concise, crash-proof utilities without imports everywhere.
-
-## Features
-- **Global Extensions**: One import unlocks `String.prototype.cap()`, `F3.isArr(value)`, etc.—no destructuring needed.
-- **Safe & Concise**: Guards against nil/empty values (e.g., `F3.arr.safe(arr)` returns `[]` if invalid).
-- **Type Guards**: Fast checks for arrays, objects, strings, etc., with `F3.typeOf(value)`.
-- **Logging Utils**: Flexible console helpers like `F3.logs(...args)`, `F3.log.obj(obj, ...rest)`, and catch-specific loggers.
-- **String & Object Helpers**: URL fabrication, templating, JSON-safe stringifying (handles circular refs).
-- **Error Handling**: Quick catch wrappers like `F3.catch.res(first, ...logs)` for graceful returns.
-- **No Dependencies**: Pure JS (Node 14+; works in browsers via `globalThis`).
-
-## Installation
-```bash
-npm install @fullstackunicorn/initialize
-```
-```bash
-yarn add @fullstackunicorn/initialize
-```
-
-## Quick Start
-Add at the top of your entry file (side-effect import—runs once):
-```javascript
-import '@fullstackunicorn/initialize';  // Now globals are extended!
-
-// String prototypes
-console.log('hello'.cap());  // "Hello"
-console.log('world!'.cut(1));  // "world"
-
-// F3 type checks
-console.log(F3.isArr([]));  // true
-console.log(F3.isNil(null));  // true
-
-// Safe accessors
-const safeObj = F3.obj.safe({});  // {}
-console.log(F3.arr.safe('not an array'));  // []
-
-// Logging
-F3.logs('Quick log:', 42);
-F3.log.obj({ user: 'Alice', age: 30 }, 'Optional prefix');  // Verbose with separator
-
-// Catch helper
-try {
-  // ... risky code ...
-} catch (err) {
-  return F3.catch.res(null, 'Handled error:', err.message);  // Logs extras, returns null
-}
-```
-
-## API Reference
-
-### String Prototype Extensions
-These add methods directly to `String.prototype` for chainable ops.
-
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `cap()` | Capitalizes first letter. | None | `string` |
-| `up()` | Converts to uppercase. | None | `string` |
-| `low()` | Converts to lowercase. | None | `string` |
-| `cut(n=1)` | Slices from end (removes last `n` chars). | `n: number` (default: 1) | `string` |
-
-### F3 Basics (Core Type Guards)
-Global `F3` namespace for common checks.
-
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `isArr(value)` | Checks if array. | `value: any` | `boolean` |
-| `isNil(value)` | Checks if null/undefined. | `value: any` | `boolean` |
-| `isFnc(value)` | Checks if function. | `value: any` | `boolean` |
-| `isObj(value)` | Checks if object (non-null). | `value: any` | `boolean` |
-| `isStr(value)` | Checks if string. | `value: any` | `boolean` |
-| `isNum(value)` | Checks if finite number. | `value: any` | `boolean` |
-| `typeOf(value)` | Returns type string (e.g., 'array', 'nil'). | `value: any` | `string` |
-
-### F3.str (String Helpers)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `isGood(str)` | Checks if non-empty trimmed string. | `str: any` | `boolean` |
-
-### F3.arr (Array Helpers)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `isGood(arr)` | Checks if non-empty array. | `arr: any` | `boolean` |
-| `safe(arr)` | Returns array or empty `[]`. | `arr: any` | `array` |
-| `isSameLength(list1, list2)` | Checks if both arrays and same length. | `list1: any`, `list2: any` | `boolean` |
-
-### F3.obj (Object Helpers)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `isGood(obj)` | Checks if non-empty object. | `obj: any` | `boolean` |
-| `safe(obj)` | Returns object or `{}`. | `obj: any` | `object` |
-| `isPlain(obj)` | Checks if plain object (no prototype). | `obj: any` | `boolean` |
-| `inKb(obj)` | Estimates size in KB (JSON-encoded). | `obj: any` | `number` |
-| `string(obj)` | Safe stringify (falls back to `String(obj)`). | `obj: any` | `string` |
-
-### F3.res (Result Validation)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `isGood(res)` | Validates result (handles errors/offline flags). | `res: any` | `boolean` |
-
-### F3 Utilities
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `fabUrl(path, params)` | Builds URL by replacing `:key` params. | `path: string`, `params: object` | `string` |
-| `replacer(string, values)` | Replaces `{{key}}` templates. | `string: string`, `values: object` | `string` |
-
-### F3.logs (Simple Logging)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `logs(...args)` | Logs args to console. | `...args: any` | `void` |
-
-### F3.log (Structured Logging)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `arr(...args)` | Logs args to console (array-style). | `...args: any` | `void` |
-| `obj(object, ...rest)` | Verbose log: Pretty-prints object keys/values with optional prefixes (handles serialization errors). | `object: object`, `...rest: any` | `void` |
-
-### F3.err (Error Status Checks)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `is500(status)` | Checks if server error (≥500). | `status: any` | `boolean` |
-| `is400(status)` | Checks if client error (400-499). | `status: any` | `boolean` |
-
-### F3.catch (Error Handling)
-| Method | Description | Parameters | Returns |
-|--------|-------------|------------|---------|
-| `res(first, ...rest)` | Returns `first`; logs `rest` (for catch blocks). | `first: any`, `...rest: any` | `any` |
-| `arr(...args)` | Logs args to console (array-style). | `...args: any` | `void` |
-| `obj(object, ...rest)` | Verbose log: Pretty-prints object keys/values with optional prefixes (handles serialization errors). | `object: object`, `...rest: any` | `void` |
-
-**Notes**:
-- All methods are pure functions (no side-effects except logging).
-- Globals persist after import—use in any scope.
-- Logging handles circular references gracefully (e.g., `[Error serializing value]` fallback).
-- For strict mode, wrap in IIFE if needed.
-
-## Examples
-### Type-Safe Array Processing
-```javascript
-import '@fullstackunicorn/initialize';
-
-function processUsers(users) {
-  const safeUsers = F3.arr.safe(users);
-  if (!F3.arr.isGood(safeUsers)) return [];
-  
-  return safeUsers.map(user => ({
-    name: F3.obj.safe(user).name.low(),
-    isValid: F3.res.isGood(user)
-  }));
-}
-```
-
-### Templated Logging
-```javascript
-import '@fullstackunicorn/initialize';
-
-const template = F3.replacer('Hello {{name}}! Age: {{age}}', { name: 'Alice', age: 30 });
-F3.logs(template);  // "Hello Alice! Age: 30"
-
-const apiUrl = F3.fabUrl('/users/:id', { id: 123 });
-F3.log.arr('Fetching:', apiUrl);  // "/users/123"
-```
-
-### Error Handling in Async
-```javascript
-import '@fullstackunicorn/initialize';
-
-async function fetchData() {
-  try {
-    // ... API call ...
-    return data;
-  } catch (err) {
-    F3.log.obj({ error: err.message, status: err.status }, 'API Error');
-    return F3.catch.res(null, 'Handled error details');
-  }
-}
-```
-
-## Contributing
-Fork the repo, add features/tests, and submit a PR. Focus on safe, concise utils!
-
-## License
-MIT © [fullstackunicorn.dev/author/lucanigido](https://fullstackunicorn.dev/author/lucanigido)