I think of scrambling as a generic method for non-specific transformations. The idea is that a given string is randomly shifted:

the DOG ate the cheese! becomes shx SAS weq sss snmwlx. I would love to be able to specify characters that should not be transformed:

copycat.scramble(input, { preserve: ['@', ' ', '!'] })

Helper utility to generate a collection of faked objects for bulk seeding

Use Case

When using RedwoodJS and seeding data with Prisma, I often find myself wanting to quickly generate N models populated with data.

For example, given the Prisma model:

model Person {
  id            Int    @id @default(autoincrement())
  fullName      String @unique
  postalAddress String
}

I may want to quickly generate 100 people.

Currently, I do something like this to construct 100 people with some fake data and then save ...

  const data: Prisma.PersonCreateArgs['data'][] = [
        ...Array(100).keys(),
      ].map((key) => {
        return {
          fullName: copycat.fullName(key),
          postalAddress: copycat.postalAddress(key),
        }
      })

// ...

  await db.person.createMany({ data, skipDuplicates: true })

But, I keep having to remember the somewhat clunky syntax

[ ...Array(100).keys(),].map((key) => {}

and it would be useful in copycat to have some method that can:

• take an argument for how many data objets to generate
• return a collection of those populated objects to save

I could envision several implementations:

• a callback to set the "generate" methods ... in the above example the returned {fullName, postalCode}
• option to return a collection (memory heavy) to use with createMany
• option to "stream" so-to-speak so can create individual via Prisma create (to support databases other than Postgres, but if you are using Snaplet, not sure why... but could be useful still).
• option to configure the "shape" like that in fictional to configure the object ... e.g., define:

const person =  {
          fullName,
          postalAddress,
        }

const person =  {
          name: fullName,
          postalAddress,
        }

so that no need to pass in the key per item.

I see that your username function may generate usernames with dots in them. In our use case we need to generate username with only alphanumeric characters and maybe dashes and underscores.

Version 0.5.0

Given only 168140 rows, we're seeing 4 UUID generation collisions across the entire set even when when copycat.uuid is fed with unique-to-that-table data. Different inputs are giving the same outputs.

This occurs for us regardless of whether we use our integer IDs or prefixed-cuids as the input.

Replication:

console.log(copycat.uuid(158012))
console.log(copycat.uuid(30939))
console.log()

console.log(copycat.uuid(99754))
console.log(copycat.uuid(132262))
console.log()

console.log(copycat.uuid(46865))
console.log(copycat.uuid(102367))
console.log()

console.log(copycat.uuid(122917))
console.log(copycat.uuid(91620))
console.log()

console.log(copycat.uuid("usr_cl74n76272kyp04ujquy1beqn"))
console.log(copycat.uuid("usr_cl74n4tp512yq04ujdi321oez"))

Output:

219f19e0-b9c4-5a42-ad8a-9a80e9b246a6
219f19e0-b9c4-5a42-ad8a-9a80e9b246a6

2ce050e8-37de-5de3-9a6a-1ad1252df1f4
2ce050e8-37de-5de3-9a6a-1ad1252df1f4

4358a1c5-c43f-5cfe-963e-13b02a3621f1
4358a1c5-c43f-5cfe-963e-13b02a3621f1

bc58abc9-eb5a-5ceb-84e5-684612eb7d7b
bc58abc9-eb5a-5ceb-84e5-684612eb7d7b

1d99d2e8-3edc-5e70-9c9c-f19919872ffa
1d99d2e8-3edc-5e70-9c9c-f19919872ffa

https://replit.com/join/krqpfrimzc-darianmoody

Adds a 'motivation' section to the readme.

Thought it'd also be a good time to share this with everyone else on the team, for their context (thus all the reviewers I've added to this PR).

Adds basic support for generating strings representing uuids.

Important notes

• I've used v5 uuids here instead of v4, since v4 is meant to be random (not what we're doing) and v5 is meant to map to some input value (what we're doing). One gotcha here, is that v5 uuids also need a namespace identifier - we just define a global one (maybe we can make the namespace an option at some point).
• The good news about v5 uuids is the security they offer:

Version-3 and version-5 UUIDs have the property that the same namespace and name will map to the same UUID. However, neither the namespace nor name can be determined from the UUID, even if one of them is specified, except by brute-force search

@peterp ^ that makes me wonder about PII with copycat in general - I have no idea what guarantees fictional offers here - it might be technically possible for people to infer the input values from the output values given by copycat. That depends on what string-hash's algorithm offers. I think we might be able to guarantee this for everything provided by fictional if we get a guarantee that the hash is not reversible, I guess we'd want that, right?

Currently, copycat.scramble(-123) will return NaN because the - is converted into, for example, a "g".

I think this is unexpected and undesirable behaviour, especially when used with snaplet, as a typical use case is:

// ...
a_number_column: copycat.scramble(row.a_number_column),
// ...

Which will work when row.a_number_column is positive, but not when it is negative. The work around would be to manually convert all your numbers to strings, then add "-" to the preserve options, then cast it back to the appropriate number type, but obviously that's not fun.

This PR implement's fictional's someOf which:

Takes in an identifying input value and an array of values, repeatedly picks items from that array a number of times within the given range. Each item will be picked no more than once.

someOf('id-23', [1, 2], ['red', 'green', 'blue'])
// =>
[
  'green'
]

This is useful when seeding string arrays seen here as tags in Prisma models like:

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String
  tags      String[]
}

While the following oneOf can be performed:

copycat.oneOf([tech,life,music,art,science]),

There was no way in copycat to make an array like ['tech', 'art'].

The someOf function now lets you generate deterministic collections.

Context

username and email need to be improved as far as collisions (different inputs returning the same outputs) are concerned:

• from measurements done (see #29 and stats below), the worst case dataset size at which collisions were observed was around 9000 for username and 8700 for email. This means collisions might happen at datasets larger than 9000, which is not a very uncommon size for production databases.
• username and email are used for values that usually need to be unique in a database
  • uuid also of course, though since that is basically proxying straight through to a uuid v5, I'm less worried about it.
  • Things like fullName are less likely to need to be unique - it may look a little weird if people see the names appearing multiple times, so still something worth fixing, but lower priority than values that typically need to be unique
  • There's probably still others to improve (dateString maybe?), for the same reasons, but this is a start

Approach

Add more possibilities to the return values for username and email to allow for a larger output range, then measure with the collision script again.

While I was there, I also added limit support for username (see #30 for context), and some improvements to limit logic. I also made some improvements to the collisions script. I've added PR comments for these things for more context.

Measurements

before:

{"methodName":"username","mean":"59674.56","stddev":"29524.62","moe":"0.14","runs":50,"n":50,"min":9005,"max":145998,"sum":2983728,"hasCollided":true,"duration":379735}
{"methodName":"email","mean":"276483.20","stddev":"179478.58","moe":"0.18","runs":50,"n":50,"min":8706,"max":849407,"sum":13824160,"hasCollided":true,"duration":2543995}

after:

{"methodName":"username","mean":"800847.73","stddev":"138023.51","moe":"0.10","runs":50,"n":11,"min":485308,"max":994067,"sum":999999,"hasCollided":true,"duration":7921728}
{"methodName":"email","mean":null,"stddev":null,"moe":null,"runs":50,"n":0,"min":null,"max":null,"sum":999999,"hasCollided":false,"duration":19710157}

Note how there were only 11 runs for username that had collisions - for the rest, we generated 999999 values without finding any collision.

email's stats look strange, but that's because no collisions were found at all - for 50 runs, where in of those runs we generated 999999 values without finding any collision.

Video with context

https://www.loom.com/share/b94094839ca04524ab661b8837eebf6e

Problem

At the moment, copycat gives you the ability to generate some fake value corresponding to some input value, for example:

copycat.email('[email protected]')
// => '[email protected]'

However, there is currently no way to restrict the generated values to be within a given character limit.

At snaplet, we make use of copycat to replace real values in a database with fake values.

This is where the problem comes in: the real values in the database are within some character limit. However, the fake values generated by copycat that we're replacing them with are not always within this same character limit. As a result, we aren't able to use these fake values.

Solution

Add a limit option to each copycat API method that generates a string, for example:

// generated result will be <= 20 characters
copycat.email('[email protected]', { limit: 20 })

Approach

Copycat makes use of composition to generate values. For example, copycat.email() makes use of copycat.firstName() and copycat.lastName().

The idea is to have each component in each layer of composition be aware of the character limit. For composites like email, allocate a limit to each component. For example, if the limit is 25, then give 5 as a limit for firstName.

Then, for each primitive/leaf (the end of the chain of composition), have it restrict its output to be within that limit. For example, firstName makes use of oneOf(), and uses it to pick from an array of first names (provided by faker). So this PR replaces this oneOf() usage with a new oneOfString() function, which will only pick from the list of values that are within that limit. If none are found, it defaults to using copycat.word().

For more context on the approach, take a look at the video: https://www.loom.com/share/b94094839ca04524ab661b8837eebf6e

Context

We currently have very little information on how likely collisions are for each of copycat's API methods. For some methods (e.g. bool), these are trivial or unimportant. For data types that typically need to be unique (e.g. uuid or email), this is important information to know: it allows us to know where in the API we need to improve to make collisions less likely, and lets our users know how likely collisions will be for their use case.

Approach

* For each API method in the shortlist:
   * Until the stopping conditions are met (see below):
     * Run the method with a new uuid v4 as input until the first collision is found, or until we've iterated 999,999 times
     * Record the data set size at which the first collision happened as a datapoint
   * Output the obtained stats (e.g. mean, stddev, margin of error)

// The stopping conditions
* Both of these must be true:
 * We've run the method a minimum (100); or
 * Either
   * The margin of error is under a lower threshold (`0.05`); or
   * The margin of error is under a higher threshold (`0.10`), but the sum (sum of first collision dataset sizes obtained so far) is over a higher threshold (999,999)

Since the task here is number-crunching, we do this using a worker farm to leverage multiple cpu cores to get results faster.

Why complicate the logic for the stopping conditions?

Ideally, we could only check two things: that our runs (the set of first collision data set sizes) is over a minimum threshold, and that our margin of error is under a maximum threshold.

Unfortunately, this isn't very computationally feasible for methods with large numbers for their first collision dataset size - it would just take too long to reach a lower margin of error. So we make a compromise, and allow for a higher margin of error (0.10 rather than 0.05) for methods with high numbers for their first collision data set size.

For example, the first collision dataset size for int is very large - so in this case, it isn't very feasible to run this until we obtained 0.05. Let's say we ran it 100 times, and in total, all of the runs (i.e. all of the first collision data set sizes) summed up to over 999,999. We then decide that we're happy enough with a margin of error of 0.10, and stop there.

Why not analyse for the theoretical probabilities instead?

We're taking an empirical approach here, rather than analysing the code to work out the theoretical probabilities. The answer is that it is difficult for us to do this for each and every copycat API method in question, and know for certain these calculations are accurate - there are just too many different variables at play influencing the probabilities, and we wouldn't really know for sure if we've accounted for all of them. The only way we can know how the collision probabilities look in practice, is to actually run the code.

Limitations

• I must admit that I know very little about the areas I'm wondering around in with this PR: both hash collision probabilities, and stats. If there's something important I'm missing with the approach I'm taking, I'd like to know!
• The approach required taking some shortcuts, since calculating the probabilities within better margins of error for some of the methods would take infeasibly long. See Why such complex logic for the stopping conditions? above for more on this.

How to read the results

For each api method: *mean is roughly: the average data set size at which a collision happened (arithmetic mean)

• stddev is the standard deviation
• min is the worst-case run - the smallest data set size at which first collision happened
• max is the best-case run - the largest data set size at which first collision happened
• runs is the number of times we tested the api method before deciding the stats are "good enough"
• sum is the sum of all the runs - the total number of times the method was called
• moe, the "margin of error", basically means: we are 95% certain the "real" average dataset size at which the first collision happens is within x % of mean - for example, a moe of 0.05 means we are 95% certain the "real" average data set size at which the first collision happens is within 5 % of mean
• hasCollided, if we reached the maximum dataset size that we test collisions for (999,999)

Results

Incomplete list (have yet to tweak the script to actually finish running in a reasonable time for the other methods):

{"methodName":"dateString","mean":"414.61","stddev":"214.23","moe":"0.05","runs":411,"min":5,"max":1412,"sum":170404,"hasCollided":true}
{"methodName":"fullName","mean":"1574.32","stddev":"784.96","moe":"0.05","runs":383,"min":75,"max":4853,"sum":602964,"hasCollided":true}
{"methodName":"streetAddress","mean":"22367.15","stddev":"12490.97","moe":"0.10","runs":122,"min":1154,"max":58605,"sum":2728792,"hasCollided":true}
{"methodName":"float","mean":"186526.06","stddev":"103245.91","moe":"0.10","runs":118,"min":12602,"max":550474,"sum":22010075,"hasCollided":true}
{"methodName":"ipv4","mean":"79714.37","stddev":"41439.56","moe":"0.10","runs":106,"min":6581,"max":205074,"sum":8449723,"hasCollided":true}
{"methodName":"email","mean":"119657.21","stddev":"59025.15","moe":"0.10","runs":100,"min":5254,"max":275462,"sum":11965721,"hasCollided":true}