const seeded = Fiona(2983938)

For demonstration purposes, a seed of 2983938 is used, but changing this should render different, but consistent results.

Fiona.Array

A seeded array generation utility, which takes qty (how many items in array) and a callback that is called with seeded which should return the value of each array item.

// input

Fiona(2983938).array(10, Fiona.Number)
// output

[
  930828,
  658401,
  284888,
  584554,
  367284,
  877802,
  619412,
  173829,
  961170,
  265921
]

You can also pass a callback for access to the seeded instance, which can be useful for adding distribution weighting to values

// input

const spreadLow = i => i ** 10
const numberCallback = seeded => seeded.distribution(spreadLow).number()

Fiona(2983938).array(10, numberCallback)
// output

[
  488306,
  15307,
  3,
  4658,
  44,
  271622,
  8313,
  0,
  672977,
  1
]

Fiona.Bool

A seeded utility to return true or false. Takes `chance` option to change the probability of true as decimal value between 0 and 1 which defaults to 0.5.

// input

Fiona(2983938).bool()
// output

false
// input

Fiona(2983938).string`The rumour is ${Fiona.Bool}`
// output

"The rumour is false"
// input

Fiona(2983938).array(5, Fiona.Bool({ chance: 0.3 }))
// output

[false,false,true,false,false]

Fiona.Choose

A seeded weighted method to select a specified number of items from a passed array.

// input

Fiona(2983938).choose(2, ['pink', 'powder blue', 'purple'])
// output

["powder blue","purple"]

Like `Fiona.OneOf`, the current distribution function will influence the choice.

// input

Fiona(2983938).distribution(i => i * i * i).choose(3, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
// output

[2,10,4]

Fiona.Date

A seeded utility to return a date as a string in format `YYYY-MM-DD`. Range is between `min` and `max` options, which default to 1940 and 2000 and can be overridden with strings parsable by the native `Date()` method. There is also a `long` to output full `Date.prototype.toISOString` format.

// input

Fiona(2983938).date()

Fiona(2983938).date({
  min: '1980',
  max: '2080',
  long: true
})
// output

"1973-03-28"

"2035-05-25T19:25:05.022Z"

Fiona.Img

A seeded utility to return a data uri of an SVG placeholder image, which takes optional arguments for width and height.

// input

Fiona(2983938).img()

Fiona(2983938).img({
  width: 200,
  height: 100
})
// output

data:image/svg+xml;utf8,%0A%20 ... etc ... %20%20%20%3C%2Fsvg%3E%0A%20%20

data:image/svg+xml;utf8,%0A%20 ... etc ... %20%20%20%3C%2Fsvg%3E%0A%20%20

Fiona.Duplicable

A seeded utility to help to produce duplicated data sometimes. By default, the seed will be picked from a pool of 10 possibilities, 10 per cent of the time.

In this example, the pool is 2, and the frequency is 0.6 so the numbers will be 373260 or 153925, 60% of the time, and the other numbers will be pseudo random according to the input seed.

// input

Fiona(2983938).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983939).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983940).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983941).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983942).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983943).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983944).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983945).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983946).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983947).duplicable({ frequency: 0.6, pool: 2 }).number()
Fiona(2983948).duplicable({ frequency: 0.6, pool: 2 }).number()
// output

153925
153925
153925
373260
153925
153925
373260
373260
773044
475855
373260

Fiona.Json

A method to return current data object as json string.

// input

Fiona(2983938).json({
  fullname: Fiona.Fullname,
  age: Fiona.Number({ max: 100 })
})
// output

{
  "fullname": "Mr Elliot Alex Thomas Wilson",
  "age": 1
}

n.b. the Fiona.Json method proxies through to Fiona.Object then formats the output, so all arguments accepted by Fiona.Object are accepted by Fiona.Json

Fiona.Lorem

A seeded utility to return lorem ipsum text, optionally takes `qty` which is approximate number of words and defaults to `15`.

// input

Fiona(2983938).lorem()

Fiona(2983938).lorem({ qty: 3 })

Fiona(2983938).lorem({ qty: 50 })
// output

reprehenderit dolor irure tempor eiusmod proident laboris nisi exercitation ea amet deserunt consequat anim cillum ut et minim

reprehenderit dolor

reprehenderit dolor irure tempor eiusmod proident laboris nisi exercitation ea amet deserunt consequat anim cillum ut et minim labore dolore veniam esse dolor enim sed laborum voluptate in in ex commodo adipisicing elit ut ut officia aliquip do non dolore culpa ad occaecat velit sint quis nulla est id eu in aliqua nostrud magna excepteur pariatur incididunt aute fugiat sit sunt qui ullamco consectetur duis

Fiona.OneOf

A seeded weighted method to select one item from a passed array.

// input

Fiona(2983938).oneOf(['pink', 'powder blue', 'purple'])
// output

powder blue

The current distribution function will influence the choice, so for example, elements appearing earlier are more likely to be chosen when a weighting reduces the pseudo random values.

// input

Fiona(2983938).distribution(i => i * i * i).oneOf([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
// output

2

Fiona.Paragraph

A seeded utility to return a paragraph of lorem ipsum text.

// input

Fiona(2983938).paragraph()
// output

Irure dolor eiusmod do proident laboris nisi nostrud ex sit deserunt commodo anim cillum aliqua labore ad ut esse minim enim in ut ullamco laborum in.  Consectetur elit veniam dolore et sunt non cillum fugiat voluptate quis pariatur enim aute adipisicing commodo labore nostrud mollit qui officia.  Labore eiusmod ullamco cupidatat occaecat nostrud culpa ut eu voluptate qui ut ut anim magna consequat sit est fugiat et duis sint nisi id aliqua exercitation enim excepteur reprehenderit.  Do mollit eu ullamco ut dolor nostrud elit consectetur velit commodo nisi fugiat enim ex ut in adipisicing in incididunt.  Ea mollit culpa in sint voluptate ad excepteur et aute aliquip id nulla duis deserunt pariatur dolore qui velit ut esse enim irure eu adipisicing proident sit in cillum incididunt tempor magna.  Lorem ipsum dolore qui proident incididunt cillum tempor ad laboris sit occaecat et sed commodo nisi ea consequat voluptate cupidatat aute aliquip culpa in sint eiusmod est.

Fiona.Regex

A very general use, seeded utility to generate a string that matches a supplied regular expression. It uses the randexp library to expand expressions, seeded by the instance of Fiona.

// input

Fiona(2983938).regex(/[01]{8} (ro|cy)bo(rg|t)s/)
// output

11110010 roborgs

When recursing objects, strings and arrays, any regex that's found will be

// input

Fiona(2983938).object({ army: /[01]{8} (ro|cy)bo(rg|t)s/, luckyNumber: Fiona.Number({ max: 10 }) })
// output

{"army":"11110010 roborgs","luckyNumber":9}
// input

Fiona(2983938).string`There is an army of ${/[01]{8} (ro|cy)bo(rg|t)s/} on their way!`
// output

There is an army of 11110010 roborgs on their way!
// input

Fiona(2983938).array(3, /[01]{8} (ro|cy)bo(rg|t)s/)
// output

["11110010 roborgs","01011010 robots","00001010 roborgs"]

n.b. the regex method is only available on the main Fiona package and is not avaliable on the Fiona core package which focusses on being very light so does not include the external libraries required to expand regular expressions.

Fiona.Sentence

A seeded utility to return a sentence of lorem ipsum text.

// input

Fiona(2983938).sentence()
// output

Reprehenderit dolor irure tempor eiusmod proident laboris nisi exercitation ea amet deserunt consequat anim cillum ut et minim labore dolore veniam esse dolor enim sed laborum voluptate in in ex commodo adipisicing.

Fiona.Number

A seeded utility to return a number, taking options min and max and precision, which default to 0 and 1,000,000 and 0.

// input

Fiona(2983938).number()
Fiona(2983938).number({ max: 10 })
Fiona(2983938).number({ min: 10, max: 20 })
// output

553972
6
16

If you add a precision, instead of an integer you will get a float rounded to specified precision.

// input

Fiona(2983938).number({ precision: 2 })
Fiona(2983938).number({ precision: -2 })
// output

553972.05
553900

Fiona.Shuffle

A seeded utility to shuffle passed array, without modifying the original input.

// input

Fiona(2983938).shuffle(['my', 'is', 'Fiona', 'name', 'Moon']).join(' ')
// output

Fiona Moon name is my

n.b. this method is actually shorthand for seeded.choose(arr.length, arr)

Fiona.Word

A seeded utility to return a single word from lorem ipsum text.

// input

Fiona(2983938).word()
// output

reprehenderit

Fiona.Distribution

A utility to manipulate the result of seeded random nambers, allowing control over the distribution of values. Distribution functions influence Fiona.Random, Fiona.Bool, Fiona.Number, Fiona.OneOf, Fiona.Choice and any other methods that rely on them. The primary use case for this method is to create more realistic data.

The distribution method sets the distribution function on a seeded instance so that future calls to seeded.random are passed through the distribution function.

// input

Fiona(2983938).number()

Fiona(2983938).distribution(i => i ** 3).number()
// output

553972

170005

In most cases the upper and lower limits remain the same, but the distribution of the values in between change as with all the predefined functions, but you can also create custom functions that can be used for any purpose, for example to clamp outputs to min and max values.

// input

const clamp = i => i < 0.5 ? 0.5 : i > 0.7 ? 0.7 : i

Fiona(2983938).distribution(clamp).random()

Fiona(2983938).distribution(clamp).number({ max: 100 })
// output

// value is clamped from 0.5-0.7
0.5539715013252439
// value is clamped from 50-70
55

Fiona.Random

Seeded version of native Math.random method.

// input

Fiona(2983938).random()
// output

0.5539715013252439

Fiona.Gender

A seeded utility to return male or female evenly distributed.

// input

Fiona(2983938).gender()
// output

female

Fiona.Title

A seeded utility to return a salutation, optionally taking a gender to adhere to.

// input

Fiona(2983938).title() // can be either gender
Fiona(2983938).title({ gender: 'male' }) // always male
// output

Dame
Sir

Fiona.namedata

The data used to generate names and salutations is exposed as Fiona.namedata which can be inspected, and modified. The data is based on Scottish census records and is structured like this sample:

Fiona.namedata = {
  male: {
    firstname: ['Jack', 'James', /* etc... */ 'Hunter', 'Zachary'],
    title: ['Mr', 'Dr', 'Sir', 'Lord']
  },
  female: {
    firstname: ['Fiona', 'Aria', 'Mia', /* etc... */ 'Matilda', 'Lauren'],
    title: ['Miss', 'Mrs', 'Dr', 'Ms', 'Dame']
  },
  lastname: ['Moon', 'Smith', 'Brown', /* etc... */ 'Mitchell', 'Fraser']
}

To change the namedata, you can assign new values to the properties of Fiona.namedata but not the object itself.

// input

Fiona(2983938).fullname()

Object.assign(Fiona.namedata, {
  male: {
    firstname: ['Austin', 'Ambrose', 'Andre', 'Arturo'],
    title: ['Lord', 'Baron', 'Count']
  },
  female: {
    firstname: ['Antonietta', 'Antonina', 'Marian', 'Antonetta'],
    title: ['Madam', 'Madame', 'Maid']
  }
})

Fiona(2983938).fullname()
// output

Dame Thea Reid
Maid Marian Reid

Fiona.Firstname

A seeded utility to return a single firstname, optionally taking a gender to adhere to.

// input

Fiona(2983938).firstname() // can be either gender
Fiona(2983938).firstname({ gender: 'male' }) // always male
// output

Lauren
Isaac

Fiona.Surname

A seeded utility to return a single surname.

// input

Fiona(2983938).surname()
// output

Reid

Fiona.Fullname

A seeded utility to return a full name, optionally taking a gender to adhere to. This is useful for producing more realistic name data where people might have multiple first and middle names, and sometimes double barrel lastnames joined with hyphen.

// input

Fiona(2983938).fullname() // can be either gender
Fiona(2983938).fullname({ gender: 'male' }) // always male
// output

Dame Thea Reid
Sir Hunter Jackson Cole Reid

Fiona.Info

Method that returns info about seeded instance, currently only the initseed property is exposed. The initseed can be used to faithfully reproduce data given the same structure.

// input

Fiona(2983938).info()
// output

{"initseed":2983938}

Fiona.register

A utility for extending Fiona with custom methods, either as a one off, or for re-usable components.

n.b. see Extending section in Overview

The Fiona.register method accepts one argument which should be a function that takes a seeded instance, and returns either a value, or the seeded instance to allow chaining.

In this example we will create a person extension that generates some data for a person, ensuring the gender is correct for each data item.

const person = (seeded, { gender }) => seeded.object({
  gender: seeded => gender || Fiona.Gender,
  title: ({ data }) => Fiona.Title({ gender: data.gender }),
  firstname: ({ data }) => Fiona.Firstname({ gender: data.gender }),
  lastname: Fiona.Surname
})

Fiona.register(['person', person])

Alternatively, if you are registering a named function, you can jut pass the function and the name of the function will be used in registration

Fiona.register(person)

Multiple functions can be registered in one call by passing multiple arguments, and configured constructor shorthands can be used to define extensions. For example, to register the person, and luckyNumber extensions, you can do something like this.

Fiona.register(person, ['luckyNumber', Fiona.Number({ max: 10 })])

A person method is added to seeded instances

// input

Fiona(2983938).person()
// output

{
  "gender": "female",
  "title": "Dr",
  "firstname": "Ayla",
  "lastname": "Moon"
}

Arguments are passed through, so in this case specifying the gender

// input

Fiona(2983938).person({ gender: 'female' })
// output

{
  "gender": "female",
  "title": "Dr",
  "firstname": "Ayla",
  "lastname": "Moon"
}

A Fiona.Person constructor is added to use as shorthand

// input

Fiona(2983938).array(3, Fiona.Person)
// output

[
  {
    "gender": "female",
    "title": "Mrs",
    "firstname": "Imogen",
    "lastname": "Murray"
  },
  {
    "gender": "male",
    "title": "Sir",
    "firstname": "Logan",
    "lastname": "Smith"
  },
  {
    "gender": "female",
    "title": "Ms",
    "firstname": "Elsie",
    "lastname": "Murray"
  }
]

The shorthand constructor can also take arguments by calling it as a function

// input

Fiona(2983938).array(3, Fiona.Person({ gender: 'female' }))
// output

[
  {
    "gender": "female",
    "title": "Mrs",
    "firstname": "Imogen",
    "lastname": "Murray"
  },
  {
    "gender": "female",
    "title": "Ms",
    "firstname": "Sophie",
    "lastname": "Smith"
  },
  {
    "gender": "female",
    "title": "Ms",
    "firstname": "Elsie",
    "lastname": "Murray"
  }
]

Fiona.Object

A method that recurses a passed data structure to resolve it's values.

// input

Fiona(2983938).object({
  fullname: Fiona.Fullname,
  age: Fiona.Number({ max: 100 }),
  luckyNumber: seeded => seeded.number({ max: 10 })
})
// output

{
  "fullname": "Mr Elliot Alex Thomas Wilson",
  "age": 1,
  "luckyNumber": 9
}

Data from prior values can be accessed on data attribute of seeded value passed to function values.

// input

Fiona(2983938).object({
  luckyNumber: seeded => seeded.number({ max: 10 }),
  unluckyNumber: seeded => 10 - seeded.data
})
// output

{
  "luckyNumber": 9,
  "unluckyNumber": 1
}

Objects can be nested

// input

Fiona(2983938).object({
    name: {
      gender: Fiona.Gender,
      title: seeded => seeded.title({ gender: seeded.data.name.gender }),
      firstname: seeded => seeded.firstname({ gender: seeded.data.name.gender }),
      middlenames: seeded => seeded.array(3, Fiona.Firstname({ gender: seeded.data.name.gender }), ' '),
      lastname: seeded => seeded.surname({ gender: seeded.data.name.gender })
    }
})
// output

{
  "name": {
    "gender": "female",
    "title": "Miss",
    "firstname": "Alice",
    "middlenames": "Mila Thea Orla",
    "lastname": "Moon"
  },
  "age": 1
}

Fiona.String

A method to populate stirng literal template with resolved values.

// input

Fiona(2983938).string`Hi ${Fiona.Firstname}, how are you?`
// output

"Hi Skye, how are you?"