Skip to content

Commit 51e7d01

Browse files
mmkalmmkal
authored
chore: more detailed docs for memorable moniker (#166)
* chore: more docs for memorable moniker * chore: change files * fix: use builder to get project list * fix: docs Co-authored-by: mmkal <[email protected]>
1 parent 965ac7d commit 51e7d01

File tree

9 files changed

+169
-14
lines changed

9 files changed

+169
-14
lines changed

‎.github/workflows/publish.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -34,5 +34,5 @@ jobs:
3434
uses: actions/github-script@v3
3535
with:
3636
script: |
37-
const release = require(`${process.env.GITHUB_WORKSPACE}/tools/builder/dist/github-release`)
38-
return release.createGitHubRelease({ context, github })
37+
const builder = require(`${process.env.GITHUB_WORKSPACE}/tools/builder`)
38+
return builder.createGitHubRelease({ context, github })

‎common/changes/memorable-moniker/moniker-docs_pr_166.json

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"comment": "chore: more detailed docs for memorable moniker (#166)",
5+
"type": "patch",
6+
"packageName": "memorable-moniker"
7+
}
8+
],
9+
"packageName": "memorable-moniker",
10+
"email": "[email protected]"
11+
}

‎packages/memorable-moniker/readme.md

+65-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,71 @@ men.next() // Stanley Coronado
4444
people.next() // Javion Farrar
4545
```
4646

47-
The `.modify` function allows tweaking the behavior of the generators. Here are some usage examples:
47+
<!-- codegen:start {preset: markdownFromJsdoc, source: src/index.ts, export: nicknames} -->
48+
#### [nicknames](./src/index.ts#L134)
49+
50+
The easiest way to get a name-generator is to import the `nicknames` generator and customise it as necessary. The `.modify(...)` method returns a new instance of a generator which extends the original. It receives a partial dictionary of parameters, or a function which returns one - the function receives the parent's configuration as an input. Parameters that can be modified:
51+
52+
**dictionaries** -- A list of "dictionaries" that words should be chosen from. These can be one of the preset values ('animal', 'femaleName', 'maleName', 'lastName', 'positiveAdjective'), or an object with a property called `words` which should be an array of strings. It's also possible to pass a list of dictionaries, in the same format. Some examples:
53+
54+
##### Example
55+
56+
```typescript
57+
const animalGenerator = nicknames.modify({
58+
dictionaries: ['animal']
59+
})
60+
const formalAnimalGenerator = nicknames.modify({
61+
dictionaries: ['animal', 'lastName']
62+
})
63+
const veryFormalAnimalGenerator = nicknames.modify({
64+
dictionaries: [{words: ['Mr', 'Ms', 'Mrs']}, 'animal', 'lastName']
65+
})
66+
```
67+
68+
**rng** -- A random-number generator. A function that should return a value between 0 and 1. The lower bound should be inclusive and the upper bound exclusive. As a convenience, the default random-number generator has an `rng.seed('...')` function to allow getting a seeded rng based on the original. Usage:
69+
70+
##### Example
71+
72+
```typescript
73+
const myNameGenerator = nicknames.modify(params => ({ rng: params.rng.seed('my-seed-value') }))
74+
console.log(myNameGenerator.next()) // always returns the same value
75+
```
76+
77+
**format** -- A function which transforms dictionary words before returning them from the generator. For example, you could convert from kebab-case to snake_case with:
78+
79+
##### Example
80+
81+
```typescript
82+
const myGenerator = nicknames.modify({
83+
format: word => word.replace(/-/g, '_')
84+
})
85+
```
86+
87+
**choose** -- A function which receives a list of words, and a random-number generator function, and should return a single word. Typically this wouldn't need to be modified.
88+
89+
**join** -- A function which receives one word from each dictionary, and is responsible for joining them into a single value. Usually the return value is a string, but if another format is returned the type will be correctly inferred.
90+
91+
##### Example
92+
93+
```typescript
94+
const informalPeople = nicknames.modify({
95+
dictionaries: [['maleName', 'femaleName'], 'lastName']
96+
join: (firstName, lastName) => `${firstName} ${lastName}`,
97+
})
98+
const formalPeople = nicknames.modify({
99+
dictionaries: [['maleName', 'femaleName'], 'lastName']
100+
join: (firstName, lastName) => `${lastName}, ${firstName}`,
101+
})
102+
const structuredPeople = nicknames.modify({
103+
dictionaries: [['maleName', 'femaleName'], 'lastName']
104+
join: (firstName, lastName) => ({ name: { first: firstName, last: lastName } }),
105+
})
106+
```
107+
<!-- codegen:end -->
108+
109+
___
110+
111+
Some usage examples of the `.modify` function tweaking generator behavior:
48112

49113
<!-- codegen:start {preset: markdownFromTests, source: src/__tests__/index.test.ts} -->
50114
Nicknames/handles:

‎packages/memorable-moniker/src/index.ts

+72-1
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ export type Dictionary = WordList | {words: string[]} | Dictionary[]
77

88
export interface Params<T> {
99
dictionaries: Dictionary[]
10-
format: (word: string) => string
1110
rng: Rng
11+
format: (word: string) => string
1212
choose: (params: {dict: string[]; rng: () => number}) => string
1313
join: (parts: string[]) => T
1414
}
@@ -18,6 +18,7 @@ export type InputParams<T> =
1818
Partial<Omit<Params<T>, 'rng'> & {
1919
rng: () => number;
2020
}>
21+
2122
export interface NameGenerator<T> {
2223
params: Params<T>
2324
modify: <U = T>(changes: InputParams<U> | ((original: Params<T>) => InputParams<U>)) => NameGenerator<U>
@@ -60,6 +61,76 @@ export const createNameGenerator = <T>(params: Params<T>): NameGenerator<T> => {
6061
}
6162
}
6263

64+
/**
65+
* The easiest way to get a name-generator is to import the `nicknames` generator and customise it as necessary.
66+
* The `.modify(...)` method returns a new instance of a generator which extends the original.
67+
* It receives a partial dictionary of parameters, or a function which returns one - the function receives the
68+
* parent's configuration as an input.
69+
*
70+
* Parameters that can be modified:
71+
*
72+
* @description **dictionaries** --
73+
*
74+
* A list of "dictionaries" that words should be chosen from. These can be one of the preset
75+
* values ('animal', 'femaleName', 'maleName', 'lastName', 'positiveAdjective'), or an object with a property
76+
* called `words` which should be an array of strings. It's also possible to pass a list of dictionaries, in the
77+
* same format. Some examples:
78+
*
79+
* @example
80+
* const animalGenerator = nicknames.modify({
81+
* dictionaries: ['animal']
82+
* })
83+
* const formalAnimalGenerator = nicknames.modify({
84+
* dictionaries: ['animal', 'lastName']
85+
* })
86+
* const veryFormalAnimalGenerator = nicknames.modify({
87+
* dictionaries: [{words: ['Mr', 'Ms', 'Mrs']}, 'animal', 'lastName']
88+
* })
89+
*
90+
* @description **rng** --
91+
*
92+
* A random-number generator. A function that should return a value between 0 and 1. The lower bound
93+
* should be inclusive and the upper bound exclusive. As a convenience, the default random-number generator
94+
* has an `rng.seed('...')` function to allow getting a seeded rng based on the original. Usage:
95+
*
96+
* @example
97+
* const myNameGenerator = nicknames.modify(params => ({ rng: params.rng.seed('my-seed-value') }))
98+
* console.log(myNameGenerator.next()) // always returns the same value
99+
*
100+
* @description **format** --
101+
*
102+
* A function which transforms dictionary words before returning them from the generator. For example,
103+
* you could convert from kebab-case to snake_case with:
104+
*
105+
* @example
106+
* const myGenerator = nicknames.modify({
107+
* format: word => word.replace(/-/g, '_')
108+
* })
109+
*
110+
* @description **choose** --
111+
*
112+
* A function which receives a list of words, and a random-number generator function, and should return
113+
* a single word. Typically this wouldn't need to be modified.
114+
*
115+
* @description **join** --
116+
*
117+
* A function which receives one word from each dictionary, and is responsible for joining them into a single
118+
* value. Usually the return value is a string, but if another format is returned the type will be correctly inferred.
119+
*
120+
* @example
121+
* const informalPeople = nicknames.modify({
122+
* dictionaries: [['maleName', 'femaleName'], 'lastName']
123+
* join: (firstName, lastName) => `${firstName} ${lastName}`,
124+
* })
125+
* const formalPeople = nicknames.modify({
126+
* dictionaries: [['maleName', 'femaleName'], 'lastName']
127+
* join: (firstName, lastName) => `${lastName}, ${firstName}`,
128+
* })
129+
* const structuredPeople = nicknames.modify({
130+
* dictionaries: [['maleName', 'femaleName'], 'lastName']
131+
* join: (firstName, lastName) => ({ name: { first: firstName, last: lastName } }),
132+
* })
133+
*/
63134
export const nicknames = createNameGenerator({
64135
dictionaries: ['positiveAdjective', 'animal'],
65136
// prettier-ignore

‎scripts/badges.js

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
const dedent = require('dedent')
2-
const readPkgUp = require('read-pkg-up')
3-
const path = require('path')
1+
const dedent = require('../packages/eslint-plugin-codegen/node_modules/dedent')
2+
const {getRushJson} = require('../tools/builder')
43

5-
/** @type {import('eslint-plugin-codegen').Preset<{}>} */
4+
/** @type {import('../packages/eslint-plugin-codegen').Preset<{}>} */
65
module.exports = params => {
7-
const {path: rootPath} = readPkgUp.sync()
8-
const {path: leafPath, packageJson: leafPkg} = readPkgUp.sync({cwd: params.meta.filename})
9-
const relativePath = path.relative(path.dirname(rootPath), path.dirname(leafPath)).replace(/\\/g, '/')
6+
const {rush} = getRushJson()
7+
const matchedProject = rush.projects.find(p => params.meta.filename.replace(/\\/g, '/').includes(p.projectFolder))
8+
const relativePath = matchedProject.projectFolder
9+
const leafPkg = {name: matchedProject.packageName}
1010

1111
const repo = 'https://github.com/mmkal/ts'
1212

‎scripts/permalink.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
const glob = require('glob')
22
const fs = require('fs')
33
const path = require('path')
4-
const readPkgUp = require('read-pkg-up')
4+
const readPkgUp = require('../packages/eslint-plugin-codegen/node_modules/read-pkg-up')
55
const childProcess = require('child_process')
66

77
const readmes = glob.sync('**/*.md', {ignore: ['**/node_modules/**', '**/CHANGELOG.md']})

‎tools/builder/.eslintrc.js

+5-2
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ module.exports = {
4141
rules: {
4242
'prettier/prettier': ['warn', require('./.prettierrc')],
4343

44-
// todo: enable
45-
// 'codegen/codegen': ['warn', {presets: {badges: require('./scripts/badges')}}],
44+
// todo: move ../../scripts somewhere that makes more sense
45+
'codegen/codegen': ['warn', {presets: {badges: require('../../scripts/badges')}}],
4646

4747
'@typescript-eslint/explicit-function-return-type': 'off',
4848
'@typescript-eslint/no-explicit-any': 'off',
@@ -158,6 +158,9 @@ function patchModuleResolver() {
158158
if (!ModuleResolver.originalResolve) {
159159
ModuleResolver.originalResolve = ModuleResolver.resolve
160160
ModuleResolver.resolve = (req, relTo) => {
161+
if (req === 'codegen') {
162+
return require('../../packages/eslint-plugin-codegen')
163+
}
161164
try {
162165
return ModuleResolver.originalResolve(req, relTo)
163166
} catch (error) {

‎tools/builder/package.json

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
"run": "./run.js",
88
"init": "./init.js"
99
},
10+
"main": "dist/index.js",
11+
"types": "dist/index.d.ts",
1012
"scripts": {
1113
"build": "node run tsc -p .",
1214
"lint": "node run eslint --cache .",

‎tools/builder/src/index.ts

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// codegen:start {preset: barrel}
2+
export * from './github-release'
3+
export * from './rush'
4+
// codegen:end

0 commit comments

Comments
 (0)