Roadmap guide (need missing features) about bogus

[salixzs]

Thank You! Your support for this excellent library is extraordinary!

[bchavez]

Hi @salixzs ,

Thank you very much for these suggestions. I am always amazed by community contributions. 👍

In general, I think it is okay for Bogus to be a superset of faker.js. In fact, I think Bogus has one additional method that faker.js lacks Finance.CreditCardNumber().

It would be great if we can support additional features as long as we don't break semantic API compatibility. For example, f.Name.LastName() still semantically returns a last name. Optional arguments like overriding locale f.Name.LastName("en") would be okay.

Additionally, I think we should avoid (as much as possible) features that require changes to core locale data that we source upstream from faker.js. I think we benefit hugely by keeping our import process as simple as drag/drop when updating locales. In an ideal world, we should be able to pull down faker.js's locale data and import it into Bogus.

Some additional thoughts:

• Random.Replace() could have placeholder for "digit-or-letter"
  • Sounds good, we could probably use * for this :)

---

• Returning random element from Enum, but not default (value=0), like f => f.Random.Enum(exceptDefault: true)­
  • Could you elaborate on this some more? AFAIK, f.Random.Enum<MyEnum>() produces values that are in an acceptable set of values for MyEnum.

---

• Getting LOREM strings of particular length, like to test storing string with maximum length in db field. f => f.Lorem.AsString(100) would return "Lorem ipsum..." as string with exactly 100 characters in length.
  • I'd probably change the naming to: f.Lorem.String(100) or f.Lorem.Characters(100). Kinda jives more with Words, Sentence, and Paragraph already in Lorem. Also, this seems semantically related f => f.Random.Letter() with a repeat.

---

• Getting random alphabet letter f => f.Random.Letter would return any letter in alphabet randomly. This might require alphabet set in locale datasets (which is not found in faker.js yet), but at least getting random English alphabet letter would suffice initially.
• Perhaps there's an easier way to do this without an alphabet defined. We could just pull f.Lorem.Words (which returns an array of words), then pull a character in that word. This way, locale's are still respected in their respective languages. Only downside, might be a lower frequency of randomness since some letters are used more than others.
• If we decide to do this, it's probably best to move f.Random.Letter to f.Lorem.Letter and add a repeat.

---

• faker.js already have pull request to change Lorem.Words to return string (and not array), which is more consistent with the rest of methods.
  • Sure, we can make this change also, if the PR is already there. Semantically, the API still returns words so I think we're still okay here.

---

• Generating Bank IBAN account numbers which would pass validation.
  • Sure, we can add this in Finance. I don't have any experience with IBAN, but from briefly glancing over Wikipedia, perhaps we can have an implementation that supports all IBAN countries.
• Generating Bank SWIFT codes - valid for testing validators.
  • Would probably go in Finance too.
• Generating fake person identity codes / social security numbers.
  • Sure thing :)

[bchavez]

Also, I'll add a contributing mark down for guidelines for future pull requests.

Basically,

New Features

Bogus a superset of faker.js's features. Adding additional features are welcome. New features and additional APIs can be added so long as we maintain semantic API compatibility with faker.js and maintain compatibility with faker.js locale data.

Contributing

Here are some helpful guidelines to keep in mind when contributing. While following them isn't absolutely required, it does help everyone to accept your pull-requests with maximum awesomeness.

• ✔️ CONSIDER adding a unit test if your PR resolves an issue or adds features.
• ✔️ DO keep pull requests small so they can be easily reviewed.
• ✔️ DO make sure unit tests pass.
• ❌ AVOID breaking the continuous integration build.
• ❌ AVOID Breaking compatibility with faker.js locale data.
• ❌ AVOID Adding new locales to Bogus. New locales should be added upstream to faker.js. See this wiki page for creating locales.

[salixzs]

For f.Random.Enum<MyEnum>() case...
There are sometimes Enums defined in code, which must be set by users (in UI), so their default values (0) are not accepted by persistence.

public enum AddressType : byte
{
    // Address Type is not Defined, must not be used in general
    Undefined = 0,
    Work = 1,
    Home = 2,
    Legal = 3
}

standard (current) randomizer might return "Undefined" (by fact it does quite frequently), but for valid test data this enum value must not be used.
It is still in enum defined, because when you create business object which uses this enum as a property - it is preset to this "Undefined" as its value is "0" - default value for byte, short, int, long.
If you remove it from enum - you get compiler warning.
Possible implementation:

public static T EnumWithoutZero<T>()
{
    T[] values = (T[])Enum.GetValues(typeof(T));
    return values[Randomizer.Seed.Next(1, values.Length)];
}

[bchavez]

Ah, makes sense now. Thank you @salixzs .

My gut feeling is hard coding to zero might not bode well for others since not everyone follows best practices for using 0 as a None/undefined value.

Perhaps, we could allow an overload for excluding values:

f.Random.Enum<MyEnum>(exclude: MyEnum.Unknown);

Let me know if you'd be okay with this.

[salixzs]

Sure! This is even better!
Thank You!

[bchavez]

Okay, I think I got most all of your requests in. Except for bank codes. I'm not familiar with SWIFT or IBAN. It requires some study for me if these things have CRC checks to pass validations like credit card numbers. I'll have to take a look at this later or I can accept a PR.

Regarding, LastName("en"). Having an override argument to LastName(localeOverride) that overrides the locale was a high impact change. It also has code smell of polluting argument parameters. Instead, a more extensible and cleaner approach I opted for something that looks like this:

var faker = new Faker<Person>("de")
    .RuleFor(p => p.LastNameNative, f => f.Name.LastName() // Generates German Lastname
    .RuleFor(p => p.LastNameTransliterated, f => f.Name["en"].LastName(); /

The benefit here is, now ALL methods get context switched and wont impact the default de locale. Essentially, all it does is return new Name("en") 👍

[salixzs]

Wow! This was fast! (overnight for me :) )

Your solutions are excellent and can be used even for more cases. Your approach with excluding enum values can also help selecting separate values for objects with two properties of the same enum type.

So far I found IBAN generation description best here:
http://www.mobilefish.com/services/random_iban_generator/random_iban_generator.php
http://www.bpfi.ie/wp-content/uploads/2014/10/MOD-97-Final-May-2013.pdf
http://www.ibancalculator.com/calculation.html
There is also library on GitHub, where generator already coded:
https://github.com/aventum-solutions/iban-api-net/blob/origin/master/Manager/IbanManager.cs
Unfortunately I do not have any code developed yet, so no fast PR from me :-(

For SWIFT best source seems to be Wikipedia:
https://en.wikipedia.org/wiki/ISO_9362
http://www.ifscswiftcodes.com/bank-swift-codes/Countries-A.htm

Regarding SSN for person - it might need more thinking, as current SSN is ok with US data only.
It seems each country has its own algorithm of creating those person id codes.
You can see examples in this online tool:
http://www.fakenamegenerator.com/ (Change Country and generate data)
Brazil: Cadastro de Pessoas Físicas, example: 470.183.002-07
Canada: SIN, example: 455 637 868
Denmark: CPR-nummer, example: 111292-1660 (using birthdate as part of code)
Finland: Henkilötunnus, example: 150740-380W (using birthdate as part of code)
etc.

[bchavez]

Perhaps we could have different namespaces that enabled Locale-specific extension methods for things like SSNs vs PersonIDs.

namespace Bogus.Extensions.Political.US{
     public static class ExtensionsForPerson{
           public static string Ssn(this Person p);
     }
}

namespace Bogus.Extensions.Political.Germany{
     public static class ExtensionsForPerson{
           public static string PersonId(this Person p);
     }
}

Bit verbose, having to write the extra (), but again void code smell of locale-specific pollution of the core API datasets.

I think I'll sleep on it a bit more. Thanks for the info about SWIFT. :) I do need to work on some non-related Bogus code tomorrow. Might be a few days before I come back to this.

[salixzs]

Appears IBAN and BIC is getting added to faker.js, too
https://github.com/Marak/faker.js/pull/286
naming goes
faker.finance.iban
faker.finance.bic

They also will have json dataset with all country formats for IBAN, so it is better to wait until next release when this is accepted PR into faker.js.

[bchavez]

Ah, yes, should have checked there first. Was going to start porting https://github.com/arturmkrtchyan/iban4j since it had an Apache license. But I'd much rather prefer a faker.js solution.

I think we'll wait on the IBAN stuff.

[bchavez]

Hi @salixzs ,

I've pushed v3.0.2 with the changes here thus far that should help you. I'm going to wait on the IBN and swift stuff until changes are merged in the main faker.js repo.

[bchavez]

@salixzs , BIC and IBAN codes are now generated in Bogus v10.0.1.

Thanks,
Brian