@wexample/js-helpers 0.0.53 → 0.0.55
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -59
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,79 +1,105 @@
|
|
|
1
1
|
# @wexample/js-helpers
|
|
2
2
|
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.55
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`@wexample/js-helpers` is a TypeScript utility library for the JavaScript side of the Wexample Suite: about thirty single-domain modules under src/Helper and src/Common, covering string casing (`stringToKebabCase`), DOM traversal (`domFindScrollParent`), filesystem walks (`nodeFsListFilesRecursively`), plus timing, queues, animation and reconnect backoff. Exports are plain named functions prefixed by their domain, so browser-only and Node-only code stay in separate files and nothing is pulled in that a caller did not import. The package ships its sources rather than a bundle — `exports` maps `./*` to `./src/*.ts` — leaving compilation to the consuming project, which needs Node 18 or later.
|
|
6
6
|
|
|
7
7
|
## Table of Contents
|
|
8
8
|
|
|
9
|
-
- [
|
|
10
|
-
- [
|
|
11
|
-
- [Versioning](#versioning)
|
|
9
|
+
- [Architecture](#architecture)
|
|
10
|
+
- [Integration in the Suite](#integration-in-the-suite)
|
|
11
|
+
- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
|
|
12
12
|
- [License](#license)
|
|
13
|
-
- [
|
|
14
|
-
- [Suite Signature](#suite-signature)
|
|
15
|
-
- [Introduction](#introduction)
|
|
13
|
+
- [About us](#about-us)
|
|
16
14
|
- [Migration Notes](#migration-notes)
|
|
17
15
|
|
|
18
|
-
##
|
|
16
|
+
## Architecture
|
|
19
17
|
|
|
20
|
-
|
|
18
|
+
### Two directories, one rule each
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
Everything lives under src, split in two:
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
- src/Helper — one file per domain, exporting free functions and frozen constant maps. `String.ts`, `Dom.ts`, `Array.ts`, `Url.ts`, `Reconnect.ts`, `NodeFs.ts`… twenty-seven of them.
|
|
23
|
+
- src/Common — the classes: `AsyncConstructor.ts` and `RetryBackoffScheduler.ts`, each a `export default abstract class` / `export default class`.
|
|
25
24
|
|
|
26
|
-
|
|
25
|
+
The split is by shape, not by subject. A behaviour that needs no instance state is a function in `Helper`; a behaviour that carries state across calls — a pending `setTimeout`, a ready flag, a callback list — becomes a class in `Common`. `Reconnect.ts` and `RetryBackoffScheduler.ts` are the same feature seen from both sides: the helper computes delays and hands back a closure-based controller, the class wraps that controller with a timer it can `cancel()`.
|
|
27
26
|
|
|
28
|
-
|
|
27
|
+
### Function names carry their file
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
There is no `index.ts` and no barrel file. What replaces it is a naming convention: every export is prefixed by its module's domain, lowercased.
|
|
31
30
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
31
|
+
```ts
|
|
32
|
+
export function stringToKebabCase(value: string): string
|
|
33
|
+
export function domFindScrollParent(element: HTMLElement, includeHidden = false): HTMLElement
|
|
34
|
+
export function nodeFsListFilesRecursively(rootPath: string, ignoredDirectoryNames: string[] = ['.git', 'node_modules']): string[]
|
|
35
|
+
export function reconnectBackoffCreateController(options: ReconnectBackoffOptions = {}): ReconnectBackoffController
|
|
36
|
+
```
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
Read a call site and you know which file to open. A new function goes in the file whose prefix it would take, or takes a new file if no prefix fits. Four older exports predate the rule and keep bare names — `waitForTransitionEnd`, `waitForAnimationEnd`, `waitForElementSize`, `buildUniqueId`, plus `expandHeight` / `collapseHeight` in `Height.ts`.
|
|
37
39
|
|
|
38
|
-
|
|
40
|
+
Files also carry a `export default` alias where one function is clearly the main one: `String.ts` ends on `export default stringToKebab;`, `Variables.ts` on `export default VARIABLES;`.
|
|
39
41
|
|
|
40
|
-
|
|
42
|
+
### The path a call takes
|
|
41
43
|
|
|
42
|
-
|
|
44
|
+
There is no runtime indirection at all. package.json maps subpaths straight onto source files:
|
|
43
45
|
|
|
44
|
-
|
|
46
|
+
```json
|
|
47
|
+
"exports": {
|
|
48
|
+
"./*": {
|
|
49
|
+
"types": "./src/*.ts",
|
|
50
|
+
"default": "./src/*.ts"
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
```
|
|
45
54
|
|
|
46
|
-
|
|
55
|
+
So `import { stringToKebabCase } from '@wexample/js-helpers/Helper/String'` resolves to src/Helper/String.ts and stops there. The consumer's bundler compiles the TypeScript; `"files": ["src"]` means the published tarball contains sources and nothing else. A caller importing `Helper/String` never loads `Helper/Dom`, which is what lets browser-only and Node-only modules coexist in one package.
|
|
47
56
|
|
|
48
|
-
|
|
57
|
+
The consequence for anyone editing: a change to a file's name or path is a breaking change to the public API, since the file path *is* the import specifier.
|
|
49
58
|
|
|
50
|
-
|
|
59
|
+
### Module dependencies are almost nil
|
|
51
60
|
|
|
52
|
-
|
|
61
|
+
Four internal imports exist in the whole tree:
|
|
53
62
|
|
|
54
|
-
|
|
63
|
+
- `Helper/Reconnect.ts` → `Helper/Time.ts` for `timeSleep`
|
|
64
|
+
- `Helper/Height.ts` → `Helper/Transition.ts` for `waitForTransitionEnd`
|
|
65
|
+
- `Common/AsyncConstructor.ts` → `Helper/Function.ts` for `functionIsType`
|
|
66
|
+
- `Common/RetryBackoffScheduler.ts` → `Helper/Reconnect.ts` for the backoff controller
|
|
55
67
|
|
|
56
|
-
|
|
68
|
+
External runtime dependencies: none. `node:fs` and `node:path` are the only imports outside the package, in `NodeFs.ts`, `NodePath.ts` and `NodeEnv.ts`. Keeping the graph this flat is deliberate — it is what makes `"sideEffects": false` and per-file imports actually pay off.
|
|
57
69
|
|
|
58
|
-
|
|
70
|
+
Import specifiers are extensionless (`from './Time'`), which works because `tsconfig.json` sets `"moduleResolution": "bundler"`. One file, `Common/AsyncConstructor.ts`, writes `from '../Helper/Function.js'` instead; both resolve, the extensionless form is the majority.
|
|
59
71
|
|
|
60
|
-
|
|
72
|
+
### Three runtime environments in one tree
|
|
61
73
|
|
|
62
|
-
|
|
74
|
+
Nothing enforces the boundary but the file name, so it has to be respected by hand:
|
|
63
75
|
|
|
64
|
-
|
|
76
|
+
- Browser-only, touching `document`, `window`, `HTMLElement`, `ResizeObserver`: `Dom`, `Location`, `Height`, `Transition`, `Animation`, `ElementSize`, `Pointer`, `Event`, `KeyCode`.
|
|
77
|
+
- Node-only, prefixed `node*`: `NodeFs`, `NodePath`, `NodeEnv`.
|
|
78
|
+
- Neutral, usable anywhere: `String`, `Array`, `Object`, `Url`, `Time`, `Bytes`, `Serialize`, `Function`, `Id`, `Queue`, `Reconnect`, `Mixin`.
|
|
65
79
|
|
|
66
|
-
|
|
80
|
+
A neutral module must not gain a DOM or `node:` reference; that is the one invariant that a new export can silently break, since `tsc` sees both lib sets.
|
|
67
81
|
|
|
68
|
-
|
|
82
|
+
### Options objects, callbacks, no globals
|
|
69
83
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
84
|
+
Stateful code takes a single options object with defaults resolved in one place, and reports progress through optional callbacks rather than events. `Queue` is the reference shape:
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
export type QueueOptions<TItem, TResult = unknown> = QueueCallbacks<TItem, TResult> & {
|
|
88
|
+
worker: QueueWorker<TItem, TResult>;
|
|
89
|
+
concurrency?: number;
|
|
90
|
+
autoStart?: boolean;
|
|
91
|
+
};
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`Reconnect` does the same with `reconnectBackoffResolveOptions()`, which merges over `DEFAULT_RECONNECT_BACKOFF_OPTIONS` and throws on invalid input (`factor must be >= 1.`), so every other function in the file can accept a partial `ReconnectBackoffOptions` and resolve it itself. Injectable seams follow the same idea: `random: () => number` in the backoff options exists so jitter can be made deterministic.
|
|
95
|
+
|
|
96
|
+
No module holds mutable module-level state. The only exported `const` are literal maps declared `as const` — `EVENT`, `KEY_CODE`, `DOM_ATTRIBUTE`, `COLORS`, `VARIABLES` — each paired with a derived type: `export type EventName = (typeof EVENT)[keyof typeof EVENT];`.
|
|
97
|
+
|
|
98
|
+
### Checking and publishing
|
|
99
|
+
|
|
100
|
+
`npm run build`, `npm run typecheck` and `npm run lint` all run `tsc --noEmit`. There is no test suite and no emitted artifact: type-checking is the whole verification step, under `"strict": true`. Publication is `npm publish --access public` from `.github/workflows/publish.yml`, triggered on `v*` tags, and `prepublishOnly` runs the build first.
|
|
101
|
+
|
|
102
|
+
tsup.config.ts configures a dual ESM/CJS bundle with `dts: true` into `dist/`, and `tsup` is a devDependency — but no script invokes it, and `dist/` is not in `files`. The shipped package is the source tree; treat the tsup config as an unused alternative path, not as the build.
|
|
77
103
|
|
|
78
104
|
## Integration in the Suite
|
|
79
105
|
|
|
@@ -101,17 +127,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
|
|
101
127
|
|
|
102
128
|
Free to use in both personal and commercial projects.
|
|
103
129
|
|
|
104
|
-
##
|
|
105
|
-
|
|
106
|
-
This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
|
|
107
|
-
|
|
108
|
-
### Related Packages
|
|
109
|
-
|
|
110
|
-
The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
|
|
111
|
-
|
|
112
|
-
Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
|
|
113
|
-
|
|
114
|
-
# About us
|
|
130
|
+
## About us
|
|
115
131
|
|
|
116
132
|
[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
|
|
117
133
|
|
|
@@ -124,9 +140,3 @@ Wexample cultivates a culture of mastery. Each package, each contribution carrie
|
|
|
124
140
|
When upgrading between major versions, refer to the migration guides in the documentation.
|
|
125
141
|
|
|
126
142
|
Breaking changes are clearly documented with upgrade paths and examples.
|
|
127
|
-
|
|
128
|
-
## Migration Notes
|
|
129
|
-
|
|
130
|
-
When upgrading between major versions, refer to the migration guides in the documentation.
|
|
131
|
-
|
|
132
|
-
Breaking changes are clearly documented with upgrade paths and examples.
|