@avstantso/std-ext 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.1.0] - 2026-01-18
+
+### Added
+
+- `Object.definePropertyOnce` - adds property only if not exists
+- `Object.definePropertiesOnce` - adds multiple properties only if not exist
+- `RegExp.escape` - escape all RegExp special characters in a string (TC39 proposal polyfill)
+- `Symbol.Has` - factory function to check and cast symbol in object
+
+### Changed
+
+- Reorganized extensions to `_std-ext/` directory structure
+- `Array.prototype` and `String.prototype` extensions now use `definePropertiesOnce`
+- `toCapitalized()` and `toUncapitalized()` now preserve string literal types
+
 ## [1.0.2] - 2026-01-15
 
 ### Fixed

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@avstantso/std-ext.svg)](https://www.npmjs.com/package/@avstantso/std-ext)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Standard JavaScript objects extension with zero dependencies. Adds useful methods to native String and Array prototypes with full TypeScript support.
+Standard JavaScript objects extension with zero dependencies. Adds useful methods to native String, Array, RegExp, Object, and Symbol with full TypeScript support.
 
 ## Features
 
@@ -32,39 +32,173 @@ Simply import the package once in your application entry point to enable all ext
 ```typescript
 import '@avstantso/std-ext';
 
-// Now all String and Array methods are available
+// Now all extensions are available
 const greeting = "hello".toCapitalized(); // "Hello"
 const items = [1, 0, 2, null, 3, false, 4].pack(); // [1, 2, 3, 4]
+const escaped = RegExp.escape("file[1].txt"); // "file\\[1\\]\\.txt"
 ```
 
 ## API Reference
 
+### RegExp Extensions
+
+#### `RegExp.escape(str)`
+
+Escapes all RegExp special characters in a string, making it safe to use in `new RegExp()`. This is a polyfill for the [TC39 RegExp.escape proposal](https://tc39.es/proposal-regex-escaping/).
+
+**Parameters:**
+- `str: string` - The string to escape
+
+**Returns:** `string` - New string with escaped RegExp characters
+
+**Escaped characters:** `\ ^ $ . * + ? ( ) [ ] { } |`
+
+**Example:**
+```typescript
+RegExp.escape("file[1].txt");     // "file\\[1\\]\\.txt"
+RegExp.escape("price: $10.00");   // "price: \\$10\\.00"
+RegExp.escape("a+b=c?");          // "a\\+b=c\\?"
+
+// Safe dynamic RegExp creation
+const userInput = "test.file[1]";
+const regex = new RegExp(RegExp.escape(userInput));
+regex.test("test.file[1]"); // true
+regex.test("testXfile11");  // false
+```
+
+### Object Extensions
+
+#### `Object.definePropertyOnce(o, p, attributes)`
+
+Adds a property to an object only if it doesn't already exist. Useful for polyfills and non-intrusive extensions. Especially handy for hot module replacement (HMR) environments like Vite, Webpack, or Parcel where modules may be re-executed multiple times.
+
+**Parameters:**
+- `o: T` - Object on which to add the property
+- `p: PropertyKey` - The property name
+- `attributes: PropertyDescriptor` - Descriptor for the property
+
+**Returns:** `T` - The object passed in
+
+**Example:**
+```typescript
+const obj = { existing: 1 };
+
+Object.definePropertyOnce(obj, 'existing', { value: 999 });
+Object.definePropertyOnce(obj, 'newProp', { value: 2 });
+
+console.log(obj.existing); // 1 (unchanged)
+console.log(obj.newProp);  // 2 (added)
+
+// Useful for polyfills
+Object.definePropertyOnce(String.prototype, 'myMethod', {
+  value() { return this.toUpperCase(); }
+});
+```
+
+#### `Object.definePropertiesOnce(o, properties)`
+
+Adds multiple properties to an object, skipping any that already exist. Same HMR benefits as `definePropertyOnce`.
+
+**Parameters:**
+- `o: T` - Object on which to add the properties
+- `properties: PropertyDescriptorMap` - Object containing property descriptors
+
+**Returns:** `T` - The object passed in
+
+**Example:**
+```typescript
+const obj = { a: 1 };
+
+Object.definePropertiesOnce(obj, {
+  a: { value: 999 },  // skipped - already exists
+  b: { value: 2 },    // added
+  c: { value: 3 }     // added
+});
+
+console.log(obj); // { a: 1, b: 2, c: 3 }
+```
+
+### Symbol Extensions
+
+#### `Symbol.Has(symb, resultTemplate?)`
+
+Creates a type guard function that checks if an object has a specific symbol property. Returns a reusable checker function with proper TypeScript type narrowing.
+
+**Parameters:**
+- `symb: symbol` - The symbol to check for
+- `resultTemplate?: R` - Optional type-only argument to infer the symbol's value type (not used at runtime)
+
+**Returns:** `(obj: unknown) => obj is { [K in Symb]: R }` - Type guard function
+
+**Example:**
+```typescript
+const mySymbol = Symbol('mySymbol');
+const hasMySymbol = Symbol.Has(mySymbol);
+
+const obj1 = { [mySymbol]: 'value' };
+const obj2 = { foo: 'bar' };
+
+hasMySymbol(obj1); // true
+hasMySymbol(obj2); // false
+hasMySymbol(null); // false (safe with nullish values)
+
+// Works great with well-known symbols
+const hasIterator = Symbol.Has(Symbol.iterator);
+
+hasIterator([]);        // true
+hasIterator('string');  // true
+hasIterator(new Map()); // true
+hasIterator({});        // false
+
+// Type narrowing in conditionals
+const data: unknown = getExternalData();
+if (hasIterator(data)) {
+  for (const item of data) { ... } // TypeScript knows data is iterable
+}
+
+// With typed value using resultTemplate
+const symbolFreeze = Symbol('freeze');
+const hasFreeze = Symbol.Has(symbolFreeze, () => {});
+
+if (hasFreeze(obj)) {
+  obj[symbolFreeze](); // TypeScript knows it's () => void
+}
+```
+
 ### String Extensions
 
 #### `toCapitalized()`
 
 Capitalizes the first character of the string.
 
-**Returns:** `Capitalize<string>`
+**Returns:** `Capitalize<S>` where `S` is the string literal type
 
 **Example:**
 ```typescript
 "hello".toCapitalized(); // "Hello"
 "world".toCapitalized(); // "World"
 "".toCapitalized();      // ""
+
+// Preserves literal types
+const a = 'foo' as const;
+const b = a.toCapitalized(); // type is 'Foo', not string
 ```
 
 #### `toUncapitalized()`
 
 Uncapitalizes the first character of the string.
 
-**Returns:** `Uncapitalize<string>`
+**Returns:** `Uncapitalize<S>` where `S` is the string literal type
 
 **Example:**
 ```typescript
 "Hello".toUncapitalized(); // "hello"
 "World".toUncapitalized(); // "world"
 "".toUncapitalized();      // ""
+
+// Preserves literal types
+const a = 'FOO' as const;
+const b = a.toUncapitalized(); // type is 'fOO', not string
 ```
 
 ### Array Extensions
@@ -82,6 +216,39 @@ Filters out all falsy values from the array (false, 0, "", null, undefined, NaN)
 [1, 0, 2, null, 3, false, 4].pack();           // [1, 2, 3, 4]
 ["a", "", "b", null, "c"].pack();              // ["a", "b", "c"]
 [true, false, true, undefined].pack();         // [true, true]
+
+// Real world example: React conditional CSS classes
+function Button({ isActive, isDisabled, isLoading }) {
+  return (
+    <button
+      className={[
+        'btn',
+        isActive && 'btn--active',
+        isDisabled && 'btn--disabled',
+        isLoading && 'btn--loading'
+      ].pack().join(' ')}
+    >
+      Click me
+    </button>
+  );
+}
+
+// Compare to the alternative without pack():
+function Button({ isActive, isDisabled, isLoading }) {
+  return (
+    <button
+      className={`btn${
+        isActive ? ' btn--active' : ''
+      }${
+        isDisabled ? ' btn--disabled' : ''
+      }${
+        isLoading ? ' btn--loading' : ''
+      }`}
+    >
+      Click me
+    </button>
+  );
+}
 ```
 
 #### `peek()`

package/package.json

@@ -2,7 +2,7 @@
   "name": "@avstantso/std-ext",
   "license": "MIT",
   "author": "avstantso",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Standard JS objects extension. Zero-dependencies",
   "keywords": [
     "String",

package/dist/array.d.ts

@@ -1,42 +0,0 @@
-declare namespace AVStantso.Array {
-    /**
-     * @summary Select `Array<T>` or `ReadonlyArray<T>` by `[W]ritable`
-     */
-    type RW<W extends boolean, T = unknown> = W extends true ? Array<T> : ReadonlyArray<T>;
-    /**
-     * @summary Key of `AVStantso.Array.RW<W>`
-     */
-    type Key<W extends boolean> = keyof {
-        [K in keyof RW<W> as `${Extract<K, string>}`]: 0;
-    };
-    namespace Key {
-        /**
-         * @summary Immutable array key
-         */
-        type R = Key<false>;
-        /**
-         * @summary Mutable array key
-         */
-        type RW = Key<true>;
-        /**
-         * @summary Mutation key only
-         */
-        type W = Exclude<RW, R>;
-    }
-    interface Ex<W extends boolean, T> {
-        /**
-         * @summary Filter all not `falsy` items
-         * @returns New array with all not `falsy` items
-         */
-        pack(): Array<T>;
-        /**
-         * @summary Get last item. Array not changes
-         * @returns Last item or `undefined`, if array empty. Array not changes
-         */
-        peek(): T;
-    }
-}
-declare interface ReadonlyArray<T> extends AVStantso.Array.Ex<false, T> {
-}
-declare interface Array<T> extends AVStantso.Array.Ex<true, T> {
-}

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-import './array';
-import './string';

package/dist/index.js

@@ -1,26 +0,0 @@
-'use strict';
-
-Object.defineProperties(Array.prototype, {
-    pack: {
-        value() {
-            return this && this.filter((item) => item);
-        }
-    },
-    peek: {
-        value() {
-            return this && this.at(-1);
-        }
-    }
-});
-
-Object.defineProperty(String.prototype, 'toCapitalized', {
-    value() {
-        return this && this.charAt(0).toLocaleUpperCase() + this.slice(1);
-    }
-});
-Object.defineProperty(String.prototype, 'toUncapitalized', {
-    value() {
-        return this && this.charAt(0).toLocaleLowerCase() + this.slice(1);
-    }
-});
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":["../src/array.ts","../src/string.ts"],"sourcesContent":["namespace AVStantso.Array {\n  /**\n   * @summary Select `Array<T>` or `ReadonlyArray<T>` by `[W]ritable`\n   */\n  export type RW<W extends boolean, T = unknown> = W extends true\n    ? Array<T>\n    : ReadonlyArray<T>;\n\n  /**\n   * @summary Key of `AVStantso.Array.RW<W>`\n   */\n  export type Key<W extends boolean> = keyof {\n    [K in keyof RW<W> as `${Extract<K, string>}`]: 0;\n  };\n\n  export namespace Key {\n    /**\n     * @summary Immutable array key\n     */\n    export type R = Key<false>;\n\n    /**\n     * @summary Mutable array key\n     */\n    export type RW = Key<true>;\n\n    /**\n     * @summary Mutation key only\n     */\n    export type W = Exclude<RW, R>;\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  export interface Ex<W extends boolean, T> {\n    /**\n     * @summary Filter all not `falsy` items\n     * @returns New array with all not `falsy` items\n     */\n    pack(): Array<T>;\n\n    /**\n     * @summary Get last item. Array not changes\n     * @returns Last item or `undefined`, if array empty. Array not changes\n     */\n    peek(): T;\n  }\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\ndeclare interface ReadonlyArray<T> extends AVStantso.Array.Ex<false, T> { }\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\ndeclare interface Array<T> extends AVStantso.Array.Ex<true, T> { }\n\nObject.defineProperties(Array.prototype, {\n  pack: {\n    value() {\n      return this && this.filter((item: unknown) => item);\n    }\n  },\n  peek: {\n    value() {\n      return this && this.at(-1);\n    }\n  }\n});\n","// eslint-disable-next-line @typescript-eslint/no-unused-vars\ndeclare interface String {\n  toCapitalized(): Capitalize<string>;\n  toUncapitalized(): Uncapitalize<string>;\n}\n\nObject.defineProperty(String.prototype, 'toCapitalized', {\n  value() {\n    return this && this.charAt(0).toLocaleUpperCase() + this.slice(1);\n  }\n});\n\nObject.defineProperty(String.prototype, 'toUncapitalized', {\n  value() {\n    return this && this.charAt(0).toLocaleLowerCase() + this.slice(1);\n  }\n});\n"],"names":[],"mappings":";;AAqDA,MAAM,CAAC,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE;AACvC,IAAA,IAAI,EAAE;QACJ,KAAK,GAAA;AACH,YAAA,OAAO,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,IAAa,KAAK,IAAI,CAAC;QACrD;AACD,KAAA;AACD,IAAA,IAAI,EAAE;QACJ,KAAK,GAAA;YACH,OAAO,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC5B;AACD;AACF,CAAA,CAAC;;AC1DF,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,EAAE,eAAe,EAAE;IACvD,KAAK,GAAA;AACH,QAAA,OAAO,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE;AACD,CAAA,CAAC;AAEF,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,EAAE,iBAAiB,EAAE;IACzD,KAAK,GAAA;AACH,QAAA,OAAO,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE;AACD,CAAA,CAAC;;"}

package/dist/string.d.ts

@@ -1,4 +0,0 @@
-declare interface String {
-    toCapitalized(): Capitalize<string>;
-    toUncapitalized(): Uncapitalize<string>;
-}