Installations
npm install @omegion1npm/itaque-est-reiciendis
Developer Guide
Typescript
No
Module System
CommonJS
Node Version
20.12.2
NPM Version
10.5.0
Score
48.1
Supply Chain
48.1
Quality
75.7
Maintenance
100
Vulnerability
99.6
License
Releases
Contributors
Unable to fetch Contributors
Languages
JavaScript (100%)
Developer
omegion1npm
Download Statistics
Total Downloads
148
Last Day
1
Last Week
1
Last Month
4
Last Year
148
GitHub Statistics
1,920 Commits
1 Branches
1 Contributors
Package Meta Information
Latest Version
1.0.0
Package Id
@omegion1npm/itaque-est-reiciendis@1.0.0
Unpacked Size
27.75 kB
Size
10.21 kB
File Count
10
NPM Version
10.5.0
Node Version
20.12.2
Publised On
30 Apr 2024
Total Downloads
Cumulative downloads
Total Downloads
148
Last day
0%
1
Compared to previous day
Last week
0%
1
Compared to previous week
Last month
-71.4%
4
Compared to previous month
Last year
0%
148
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
28
Finitio.js
Finitio is a language for capturing information structure. A little bit like "JSON/XML schema" but on steroids. An example is show below. For more information about Finitio itself, see www.@omegion1npm/itaque-est-reiciendis.io
@import @omegion1npm/itaque-est-reiciendis/data
Uuid = String( s | s =~ /^[a-z0-9-]{36}$/ )
Name = String( s | s.length > 0 )
Temp = <celsius> Real( f | f >= 33.0 && f <= 45.0 )
{
patient : {
id : Uuid
name : Name
dob : Date( d | alive: d.year > 1890 )
}
symptoms : [ String( s | s.size > 0 ) ]
temperature : Temp
}
Finitio.js is the javascript binding of Finitio. It allows defining schemas and validating/coercing data against them in an idiomatic javascript way.
Status
Features
Finitio.js is a stable and mature implementation conforming to Finitio 0.4. It also comes with the following tooling:
- A
@omegion1npm/itaque-est-reiciendis-js
command line for validating data from a shell - A bundler for preparing schemas and systems for use in a browser
- Nice error management strategy with understandable messages & stacks
- Try it online, at http://@omegion1npm/itaque-est-reiciendis.io/try
- A standard library, especially
@omegion1npm/itaque-est-reiciendis/data
for dressing numbers, dates times without pain, despite JavaScript weaknesses in that regard - Experimental undressing strategy
Getting started in Shell
-
Validating data against as schema and showing all errors
@omegion1npm/itaque-est-reiciendis-js -v schema.fio data.json
-
Better understanding where validation errors come from
@omegion1npm/itaque-est-reiciendis-js --stack -v schema.fio data.json
-
Fail fast option (stop on first validation error)
@omegion1npm/itaque-est-reiciendis-js --stack --fast -v schema.fio data.json
-
Compiling a schema for the browser
@omegion1npm/itaque-est-reiciendis-js -c schema.fio
Getting started in JavaScript
Roughly, getting started with @omegion1npm/itaque-est-reiciendis.js in JavaScript code works as follows:
1var Finitio = require('../index.js'); 2 3// Parses a schema and compiles to a System object 4var schema = " \n\ 5Name = String( s | nonEmpty: s.length>0 ) \n\ 6[{ who: Name }] \n\ 7" 8var system = Finitio.system(schema); 9 10// Some data, with invalid tuples according to the schema above 11var data = [ 12 { who: 'Finitio' }, 13 { who: 'JavaScript' }, 14 { who: '' }, 15 { who: 12 } 16]; 17 18// dress/validate some data 19try { 20 system.dress(data); 21} catch (ex) { 22 // explain the validation errors 23 // `explainTree` can be used for better debugging 24 console.log(ex.explain()); 25}
Imports and Standard Library
Since Finitio 0.4, imports are supported to split complex schemas in multiple files. A standard library has also been started, from which you can import too.
# import types from utils.fio and ../support/tools.fio into this schema
@import ./utils
@import ../support/tools
# import from the standard library
@import @omegion1npm/itaque-est-reiciendis/data
# import from the web
@import http://my-@omegion1npm/itaque-est-reiciendis-schemas.org/somewhere/somefile
Refer to Finitio's web site for more documentation about imports and the standard library.
Bundling schemas (for the browser)
Complex @omegion1npm/itaque-est-reiciendis schemas can also be bundled as one self-contained javascript file. The bundling process does not (yet) make schemas independent of @omegion1npm/itaque-est-reiciendis.js itself (i.e. @omegion1npm/itaque-est-reiciendis is still a runtime dependency). However, bundling can be used for:
- Checking the validity of your schema ahead of test & runtime time
- Avoiding costly parsing at runtime
- Avoiding the import resolution mechanism to occur at runtime, by bundling all dependencies in one file, including schemas from the standard library and the web.
- Making your schema ready in the browser, in particular not dependent of the file system (for relative imports).
Bundling can be done from a shell, as follows (the --fast option is just used to stop on the first schema error):
1@omegion1npm/itaque-est-reiciendis-js --fast --bundle schema.fio
This will generate a javascript bunch of code. This code, when evaluated returns a function that can be injected with the world to obtain the compiled schema (see more about the world later). In practice:
1var schemaCompiler = require('generated-@omegion1npm/itaque-est-reiciendis-bundle.js'); 2var system = schemaCompiler(); 3system.dress({ some: 'data' });
In the scenario above, the schemaCompiler will require @omegion1npm/itaque-est-reiciendis by itself. In some situations, such as when you use external javascript references, however, you will need to pass a world instance for it to work properly. This is explained in the next section.
Advanced scenarios and the World concept
Finitio relies on a World concept for:
- Resolving external references at compile time, (e.g. JavaScript's
String, Number, Regexp or your own 'classes' when using ADTs), i.e. when you
call
Finitio.system
. - Resolving
@import
s - Managing dressing options, e.g.
failfast
In simple scenarios you won't need to hack with the world concept. However,
for advanced usage of Finitio, understanding the world
argument taken by
many citizen is important. Those citizen are:
Finitio.system(source, world)
(e.g. for resolving builtins and ADTs)Finitio.compile(source, world)
(idem, when compiling for the browser)Type.dress(value, world)
(to make the world available to native information contracts)System.dress(value, world)
(idem, delegated to main type)
Resolving external references at compile time
The first scenario is the most frequent, where the world is used to resolve
extenal references. Finitio has a default world that already resolves
references to JavaScript main constants such as Number
of String
. Your
world, providing references to you own 'classes' will be merged with the
default one:
1// your own abstractions 2var MyLibrary = { Color: function(){ } }; 3 4// you need to provide external references in world's JsTypes 5var world = { JsTypes: { 'MyJsColor': MyLibrary.Color } }; 6 7// the world will be use to resolve `.MyJsColor` below. `.String` is already 8// resolved by the default world 9var system = Finitio.system("Color = .MyJsColor <as> .String", world);
Passing options at dressing time
The following options can be set to the World when dressing & validating data:
failfast
: When true, stops dressing as soon as a first validation error is found. When false (default), dressing will collect all errors before failing. The default option may be costly on complex schema, as it keeps the entire failure tree.
Hacking in native information contracts
The world can also be used in internal and external information contracts. This is not recommended, as it means that you dresser have side effects, but it might be useful sometimes.
As an example, suppose that you have a global registry with elements as follows (that might be a database, or the file system or whatever):
1var Registry = { 2 1: { foo: 'bar' }, 3 2: { bar: 'baz' } 4};
Maybe you want to provide an information contract for resolving ids to actual data through that registry. Finitio does not allow you to do it with explicit contracts, you want be able to resolve ids that way:
Component = .Object <id> .Number \( id | ??? )
In contract, native contracts receive the world as second argument, meaning that following scenario will work:
1var ComponentContract = { 2 dress: function(id, world){ 3 var resolved = world.TheRegistry[id]; 4 if (resolved){ 5 return resolved; 6 } else { 7 throw new Error("No such component"); 8 } 9 } 10}
At compile time:
1var world = { JsTypes: { ComponentContract: ComponentContract }}; 2var schema = 'Component = .Object <id> .Number .ComponentContract'; 3var system = Finitio.system(schema, world);
At dressing time:
1var world = { TheRegistry: Registry }; 2var dressed = system.Component.dress(2, world);
More on Internal Information Contracts
Abstract Data Types can be defined and dressed using Finitio.js, provided you
register them as show previously. Let take the usual Color
example. (We
"qualify" type names below only to avoid confusion, in practice, one would
probably use Color
everywhere.)
In Finitio,
Byte = .Number // should be defined more accurately, of course
Color = .JsColor <rgb> { r: Byte, g: Byte, b: Byte }
In Javascript,
1Color = function(r, g, b) { 2 this.r = r; 3 this.g = g; 4 this.b = b; 5} 6Color.rgb = function(tuple) { 7 return new Color(tuple.r, tuple.g, tuple.b); 8} 9Color.prototype.toRgb = function(color){ 10 return { 11 r: color.r, 12 g: color.g, 13 b: color.b 14 }; 15}
At compile time:
1schema = "..." // as shown above 2 3// you must let Finitio.js know about JsColor, in the following way 4system = Finitio.system(schema, { JsTypes: { JsColor: Color } }); 5 6// dressing will then work as expected 7color = system.Color.dress({r: 12, g: 125, b: 98});
More on External Information Contracts
Finitio.js also allows defining so-called 'external' information contracts for situations where implementing the dresser and undresser functions as show above is not possible or not wanted.
In Finitio,
Byte = .Number // should be defined more accurately, of course
Color = .JsColor <rgb> { r: Byte, g: Byte, b: Byte } .ExternalContract
In Javascript,
1Color = function(r, g, b) { 2 this.r = r; 3 this.g = g; 4 this.b = b; 5} 6ColorContract = { 7 dress: function(tuple) { 8 return new Color(tuple.r, tuple.g, tuple.b); 9 }, 10 undress: function(color) { 11 return { 12 r: color.r, 13 g: color.g, 14 b: color.b 15 }; 16 } 17}
At compile time:
1schema = "..." // as shown above 2 3// you must let Finitio.js know about ExternalContract, in the following way 4system = Finitio.system(schema, { JsTypes: { ExternalContract: ColorContract } }); 5 6// dressing will then work as expected 7color = system.Color.dress({r: 12, g: 125, b: 98});
Representation of Finitio Types as JavaScript types
The Rep
representation function mapping Finitio types to Javascript types is
as follows:
# Any is anything in javascript
Rep(.) = any javascript value/object/stuff
# Builtins are represented by the corresponding javascript type
# Supported: Number, String, Boolean, Date and your own abstractions (see below)
Rep(.Builtin) = Builtin
# Sub types are represented by the same representation as the super type
Rep(SuperType( s | ... )) = Rep(SuperType)
# Unions are represented by the corresponding javascript types. No guaranteed
# result in terms of types, as `^` (least common super type) is difficult to
# define properly in javascript.
Rep(T1 | ... | Tn) = Rep(T1) ^ ... ^ Rep(Tn)
# Sequences are represented through javascript Arrays.
Rep([ElmType]) = Array<Rep(ElmType)>
# Sets are represented through javascript Arrays. _Finitio.js_ checks for duplicates,
# though.
Rep({ElmType}) = Array<Rep(ElmType)>
# Tuples are represented through standard javascript objects.
Rep({Ai => Ti}) = Object<{Ai: Rep(Ti)}>
# Relations are represented through Arrays of objects.
Rep({{Ai => Ti}}) = Array<Object<Ai => Rep(Ti)>>
# Abstract data types are represented through the corresponding javascript
# type when specified. ADTs behave as Union types if no type is bound.
Rep(.Builtin <rep> ...) = Builtin
No vulnerabilities found.
No security vulnerabilities found.