v0.15.0 (2026-09-06)
A large internal rewrite. Some thin top-level functions were removed outright rather than deprecated (a formal deprecation cycle starts in v0.20.0), but each has a one-to-one replacement. Options that changed a function's return type were removed. Everything else is internal: how locale state is scoped, how options are validated, and where the private modules live.
Features
NeoFaker.seed/1seeds:randfor the calling process, for reproducible output in tests.NeoFaker.Person.gender/1takes a:formatoption (:binary,:short_binary,:non_binary, or:all, which pools the binary and non-binary identities). Replacesbinary_gender/1,short_binary_gender/1,non_binary_gender/1.NeoFaker.Address.latitude/1andlongitude/1return a single coordinate component.NeoFaker.HTTP.user_agent/1takestype: :ai, drawing from a new list of AI crawler and agent bot tokens ("gptbot","claude-user","perplexitybot", and so on);:allincludes them. Crawler user-agents are now bare bot tokens rather than full UA strings.NeoFaker.HTTP.request_method/1andall_request_methods/0now include theQUERYmethod. It counts as common, so the default (common_only: true) pool is six methods, not five.NeoFaker.Localeowns all locale state (fetch/0,get/0,set/1) and the supported-locale list (supported/0,available?/1), previously split betweenNeoFakerand the hiddenNeoFaker.Data.NeoFaker.Gravatar.random_display/0replacesrandom/0.
Breaking Changes
- Invalid options raise
NimbleOptions.ValidationError, notArgumentError. The internalHelpers.Optionswrapper is gone;NimbleOptions.validate!/2is called directly. Positional-argument and unsupported-locale errors still raiseArgumentError. :formatis removed fromNeoFaker.DateandNeoFaker.Time. They always return aDate/Timestruct; callDate.to_iso8601/1/Time.to_iso8601/1for a string. Signatures lose an argument, e.g.NeoFaker.Date.add/1,NeoFaker.Date.between/2,NeoFaker.Time.between/2; the period helpers (NeoFaker.Time.morning/0throughnight/0) andNeoFaker.Time.now/0take no arguments, whileNeoFaker.Time.add/2keeps:unit.NeoFaker.Date.past/1andNeoFaker.Date.future/1now raiseArgumentErrorfor a non-positive day count.:joinis removed fromNeoFaker.Loremparagraphs/sentences/wordsandNeoFaker.Text.words. They always return a list; join it withEnum.join/2.NeoFaker.Text.words/1no longer takes options.:typeis removed fromNeoFaker.Address.coordinate/1(always a{lat, lng}tuple) andbuilding_number/1(always a string; the second argument is gone too).:integeris removed fromNeoFaker.Boolean.boolean/1(always a boolean; the second argument is gone too).NeoFaker.Locale.set/1is process-scoped, not node-global. It writes to the process dictionary, notApplication.put_env/3, so it never leaks between processes. Useconfig :neo_faker, locale: ...for a node-wide default.- Locale-exclusive modules moved:
NeoFaker.EnUs.*/NeoFaker.IdId.*are nowNeoFaker.Locales.EnUs.*/NeoFaker.Locales.IdId.*. - Removed, each with a drop-in replacement:
NeoFaker.locale/0,set_locale/1,get_locale/0(useNeoFaker.Locale.fetch/0,set/1,get/0);Person.binary_gender/1,short_binary_gender/1,non_binary_gender/1(usegender/1);Gravatar.random/0(userandom_display/0);Data.supported_locales/0,locale_available?/1(useNeoFaker.Locale.supported/0,available?/1). NeoFaker.Internet.email/1reads only the prefixed option names now (:username_word_count,:domain_name_word_count,:tld_type), not the bare:word_count/:typefallbacks.nimble_options ~> 1.1is now a runtime dependency.
Bug Fixes
Person.first_name/1,middle_name/1,last_name/1,full_name/1,App.name/1, andColor.keyword/1now honour the configured locale when no:localeoption is passed; they hardcoded:defaultbefore.NeoFaker.Datano longer reseeds:randon the first read of a data file, which silently overrode a caller's seed.Internet.username/1,domain_name/1(type: :random), andslug/2now emit only lowercase alphanumeric segments; a word carrying a space, hyphen, apostrophe, or accent used to leak through. Phrase entries were dropped from the word list.Lorem.word/1andsentence/1no longer raiseEnum.EmptyErrorwhen the source text splits around a blank fragment.
Improvements
- Ran the full Elixir anti-pattern catalogue over
lib/and closed every finding. Beyond the return-type changes above:Map.fetch!/2instead ofMap.get/2for schema-guaranteed keys,App.package_name/1reusesFormatter.slugify/1,Person.age/2drops validation it duplicated, and two test-onlyInternet.Generatorfunctions are marked@doc false. - Private submodules (all
@moduledoc false) now follow one naming convention:<Domain>.Generatorand<Domain>.Validator. Every bareimportof a project module was replaced with analias. - Locale and data backend simplified (internal only):
priv/data/locale.exsis replaced by a module attribute inNeoFaker.Locale, andNeoFaker.Datacollapsed to oneload/3path shared byrandom_value/4andfetch!/3, which now share the per-file:defaultfallback. NeoFaker.Internet.Generatorrefactored for readability (named octet helpers, pattern-matchedreserved_ipv4?/3, a purecompress_ipv6_groups/1); output is unchanged.- Documentation pages sorted into
guides/,reference/,contributing/, andabout/subfolders, one per ExDoc sidebar group. URLs are unchanged. - Test suite overhauled across every domain; total line coverage is now 100%.
v0.14.0 (2026-03-11)
Features
- Added
NeoFaker.Data.supported_locales/0, which returns the supported locale atoms frompriv/data/locale.exs, cached in:persistent_term. - Added
NeoFaker.Gravatar.profile/2, which generates a Gravatar profile URL with:formatoption (:html,:json,:xml,:php,:vcf,:qr). - Added
NeoFaker.Gravatar.random/0, which generates a Gravatar image URL with a random size and fallback type. - Added
NeoFaker.Gravatar.fallback_types/0,default_size/0, andsize_range/0as public introspection helpers. - Added
NeoFaker.Gravatar.display/2options:rating(:g,:pg,:r,:x) and:force_default(appends&f=ywhentrue). - Added
NeoFaker.App.Validator.validate_domain!/1, which raisesArgumentErroron invalid domain strings, replacing silentMatchErrorinbundle_id/1andpackage_name/1. - Added
NeoFaker.Internet.Validator.validate_ipv4_class!/1, which raisesArgumentErroron invalid:classvalues inipv4/1, replacingFunctionClauseError. - Added
NeoFaker.Internet.Generator.reserved_ipv4?/3, a public predicate for all IANA-reserved IPv4 ranges, usable independently of the generator. - Added
NeoFaker.Helpers.Formatterfor format conversions andNeoFaker.Helpers.Optionsfor option extraction and validation. - Added
NeoFaker.IdId.Person.npwp/0for generating Indonesian tax identification numbers (NPWP). - Added
NeoFaker.Address.Generatorwithlatitude/1andlongitude/1. - Consolidated all data-access helpers into
NeoFaker.Data.
Improvements
public_ipv4/0now excludes all IANA-reserved ranges:0.0.0.0/8,10.0.0.0/8,100.64.0.0/10,127.0.0.0/8,169.254.0.0/16,172.16.0.0/12,192.0.0.0/24,192.0.2.0/24,192.88.99.0/24,192.168.0.0/16,198.18.0.0/15,198.51.100.0/24,203.0.113.0/24,224.0.0.0/4, and240.0.0.0/4. First-octet selection uses a compile-time cumulative weight table for O(1) performance.url_path/0andquery_string/0now slugify multi-word entries fromText.word/0(e.g."ice cream") (spaces become-) before use in path segments and query keys.url/1no longer produces double-TLD output (e.g."gmail.com.net") for:popularand:customdomain types; TLD is now only appended for:randomdomains.set_locale/1now validates the locale againstsupported_locales/0before storing, and the error message lists all valid values.NeoFaker.Datanow resolves the locale file via:code.priv_dir/1, fixing lookup when NeoFaker is used as a Mix dependency.Crypto.token/2's guard no longer matches any integer incorrectly;ArgumentErroris now raised only for non-positive lengths.Number.decimal/3now delegates tobetween/2before rounding, inheritingmin > maxvalidation.- Extracted
ValidatorandGeneratorsub-modules across all major modules:Address,App,Blood,Boolean,Color,Crypto,Date,Gravatar,HTTP,Internet,Lorem,Number,Person,Text, andTime. - Removed
NeoFaker.Helpers.Constantsin favour of module attributes. - Added
@docto all sub-module functions for improved autocomplete. - Bumped minimum Erlang/OTP to 28.0 and Elixir to 1.18.4. Pinned dev toolchain to OTP 28.3 and
Elixir 1.19.4 in
mise.tomland CI. - Renamed the "Available Locales" docs page to "Locales".
Bug Fixes
bundle_id/1andpackage_name/1now raiseArgumentError(notMatchError) for domains with no dot or empty strings.ipv4/1now raisesArgumentError(notFunctionClauseError) for unsupported:classvalues.public_ipv4/0no longer generates loopback, private, link-local, multicast, CGN, or test/documentation addresses.- Fixed off-by-one in
find_octet_in_table/2cumulative weight lookup. - Fixed
Address.city/0returningnilfor some locales. - Fixed
Date.birthday/3start date calculation. - Fixed crash in
Time.time_zone/0when locale data is incomplete. - Scoped
:persistent_termcache keys to tuples to prevent cross-module collisions. - Added path-traversal validation on data file names in
NeoFaker.Data. domain_name/1withtype: :customnow raisesArgumentErrorfor a non-string or empty:domain_name, preventing bad values from propagating intoemail/1andurl/1.validate_domain!/1now enforces RFC 1123 label rules, namely alphanumeric start/end, letters, digits, and hyphens only, max 63 chars per label. Rejects trailing dots,/,:, and leading/trailing hyphens.locale/0now raisesArgumentErrorfor unsupported atoms stored directly in the application env, preventingget_locale/0from reporting a different locale than generators actually use.Number.decimal/3now raisesArgumentErrorfor negative precision (wasFunctionClauseError). The@specis widened tonumber()to reflect that integer bounds are accepted.
Breaking Changes
set_locale/1raisesArgumentErrorfor any atom not inpriv/data/locale.exs(or:default). UseNeoFaker.Data.supported_locales/0to list valid values.ipv4/0(public mode) no longer returns IANA-reserved addresses. Useipv4(private: true)if you need a private range address.
Tests
- Added comprehensive
GravatarTestcoverage: size, fallback types,:rating,:force_default,profile/2formats,random/0, and all introspection helpers. - Replaced probabilistic IPv4 sampling with deterministic boundary assertions against
reserved_ipv4?/3, covering all IANA blocks at both endpoints and adjacent public addresses. Class-specific private IPv4 tests also verify full four-octet structure. - Added
AppTesterror-path coverage forbundle_id/1andpackage_name/1domain validation. - Added
CryptoTestcoverage fortoken/2length errors and hash format checks. - Added
NumberTestcoverage fordecimal/3range errors, bounds, precision, and mixed-type float generation inbetween/2. - Added
NeoFakerTestcoverage forset_locale/1andlocale/0valid and invalid inputs. - Refactored all test modules to follow ExUnit conventions:
async: true, module aliases,refuteovernot assert,foroverEnum.each, separate assertions over compoundassert.
v0.13.0 (2025-10-29)
Features
Added new module NeoFaker.Internet to handle internet-related data generation, including:
NeoFaker.Internet.tld/1for generating random top-level domains (TLDs).NeoFaker.Internet.username/1for generating random usernames.NeoFaker.Internet.domain_name/1for generating random domain names.NeoFaker.Internet.email/1for generating random email addresses.NeoFaker.Internet.ipv4/1for generating random IPv4 addresses.NeoFaker.Internet.ipv6/1for generating random IPv6 addresses.NeoFaker.Internet.mac_address/1for generating random MAC addresses.NeoFaker.Internet.url/1for generating random URLs.NeoFaker.Internet.slug/2for generating random URL slugs.
Improvements
- Changed
.tool-versionstomise.tomlfor better version management, now NeoFaker uses mise as the version manager. - Upgraded mix dependencies.
- Fixed typo in
cheat.cheatmdfile. - Refactored
NeoFaker.Data.CacheandNeoFaker.Data.Diskfor improved file handling and caching mechanisms.
Module Changes
Breaking Changes: Renamed NeoFaker.Http to NeoFaker.HTTP for consistency.
v0.12.0 (2025-06-10)
Features
- Added
NeoFaker.Addressfor generating random address components: building numbers, cities, countries, and coordinates. - Added
NeoFaker.Time.time_zone/0for generating random time zones.
Improvements
- Unified and clarified documentation for all public functions.
- Refactored generator modules:
NeoFaker.Data.Cache,NeoFaker.Data.Disk,NeoFaker.Data.Generator, andNeoFaker.Data.Resolverfor improved organization and readability. - Updated
NeoFaker.Data.Cache.put_cache!/3to useStream.uniq/1for duplicate removal before caching. - Upgraded mix dependencies.
Breaking: Renamed NeoFaker.Internet to NeoFaker.HTTP with expanded features.
NeoFaker.http (formerly NeoFaker.Internet)
- Added
Http.request_method/0for random HTTP methods. - Added
Http.referrer_policy/0for random referrer policies. - Added
Http.status_code/1for random HTTP status codes with filtering. - Enhanced
Http.user_agent/1to support:typefiltering (:browseror:crawler).
Argument Standardization
Breaking: Default arguments now use explicit atoms:
NeoFaker.Color.hex/1defaults to:six_digit(wasnil).NeoFaker.Color.keyword/1defaults to:all(wasnil).
Organization & Locale
- Split large utility modules into smaller, focused modules.
- Improved documentation and examples.
- Added Indonesian locale support.