x51 / projects // proto

@kung-fu/proto is a small utility library that wraps JavaScript primitives in fluent helpers. The package exports five wrapper factories — s(), a(), n(), obj(), helem() — plus the standalone range() helper.

Each wrapper holds a mutable internal value, so most methods modify state in place and also return the same wrapper. The chained style is canonical, but storing a reference and calling methods imperatively works identically. The schema interfaces (IString, IArray<T>, etc.) are internal — rely on TypeScript inference at the call site rather than importing them.

---// install

npm install @kung-fu/proto

---// import

import { s, a, n, obj, helem, range } from '@kung-fu/proto';

---// strings // s(value: string)

Wraps a string. Chainable transforms mutate the wrapper’s value and return this; predicates and getters return primitives.

Slugify a title (the chain mutates and the unwrap returns):

s('  Hello,   World!  ').slugify().toString();
      // "hello-world"

capFirst handles leading punctuation:

s('"hello there"').capFirst().toString();
      // '"Hello there"'
      
      s('(parens stay)').capFirst().toString();
      // "(Parens stay)"

Strip and truncate user-submitted HTML for a teaser:

const teaser = s(post.body)
          .stripHtml()
          .normalize()
          .truncateWords(40)
          .toString();

Truncate while keeping HTML structure:

s('<p>Lorem <em>ipsum dolor</em> sit amet</p>')
          .truncateWordsWithHtml(3)
          .toString();
      // "<p>Lorem <em>ipsum dolor</em></p>"

Truthy-string parser — useful for query-string flags:

s('on').toBool();      // true
      s('Yes').toBool();     // false  (only 'y' / 't' single letters match)
      s('1').toBool();       // true
      s('').toBool();        // false

Parse and update a semicolon-delimited key/value blob:

s('user:alice;role:admin;tz:utc').getValueByKey('role');
      // "admin"
      
      s('user:alice;role:admin').setValueByKey('role', 'guest').toString();
      // "user:alice;role:guest"

---// arrays // a<T>(value: T[])

Wraps an array. Generic over T at the wrapper level, but note that each’s callback types its element parameter as any.

Iterate with the index-first callback:

a(['alpha', 'beta', 'gamma']).each((i, item) => {
          console.log(`${i}: ${item}`);
      });

Loose substring contains versus strict equality:

const tags = ['javascript', 'typescript', 'rust'];
      
      a(tags).contains('script', false);   // true (substring match)
      a(tags).contains('script', true);    // false (no exact element)
      a(tags).contains('rust', true);      // true
      a(tags).indexOfPartial('type');      // 1

Reshape a primitive list for an API that wants [{ id }, …]:

a([1, 2, 3]).toObjectArray('id').toArray();
      // [{ id: 1 }, { id: 2 }, { id: 3 }]

---// numbers // n(value: number)

The wrapper is reusable — random overwrites the held value, so chaining draws new numbers from one wrapper:

const rng = n(0);
      rng.random(1, 6).toNumber();    // e.g. 4
      rng.random(1, 6).toNumber();    // e.g. 1

---// objects // obj(value: any)

Tiny helper for ad-hoc shallow merging. extend mutates the wrapped object in place using only its own enumerable properties (it filters via hasOwnProperty).

const settings = { theme: 'dark', size: 14 };
      
      obj(settings).extend({ size: 16, lineHeight: 1.5 }).toObject();
      // { theme: 'dark', size: 16, lineHeight: 1.5 }
      // settings is the same reference, mutated in place.

---// html form elements // helem(elem)

Smart wrapper around form elements. val() dispatches on nodeName + the input’s type attribute and handles each variant the way you usually want, so calling code doesn’t have to branch.

clean() normalizes line breaks in the element’s value to \r\n — useful before posting a textarea to a backend that expects DOS-style EOLs.

toHTMLElement() returns the underlying element if you need to drop back to vanilla DOM.

const input = document.querySelector('#email') as HTMLInputElement;
      
      const current = helem(input).val();         // string | number | boolean
      helem(input).val('user@example.com');
      
      // Set a date input from any common format:
      helem(dateInput).val('2026-05-06T12:00:00');   // becomes 2026-05-06
      helem(dateInput).val('05/06/2026');            // becomes 2026-05-06
      
      // Pick a radio in a named group:
      // <input type="radio" name="plan" value="pro">
      // <input type="radio" name="plan" value="free">
      helem(anyRadio).val('pro');
      
      // Read a multi-select as one string:
      helem(multi).val();   // "alpha;beta;gamma"

---// range // range(count, start?)

Returns a fresh native number[] of count sequential integers starting at start (default 1). Despite the parameter name in the source TSDoc, the first argument is the array length, not an upper bound.

range(5);        // [1, 2, 3, 4, 5]
      range(5, 10);    // [10, 11, 12, 13, 14]
      range(0);        // []

---// source

npmjs.com/package/@kung-fu/proto