Class Blueprint

Hierarchy (View Summary)

Contract
- Blueprint

Constructors

constructor

new Blueprint(layout: BlueprintLayout, skeleton?: ContractObject): Blueprint
Parameters
- layout: BlueprintLayout
  the blueprint layout
- Optionalskeleton: ContractObject
  the blueprint skeleton
Returns Blueprint
Name
Blueprint

Memberof
module:contrato

Description
Creates a new Blueprint with a given layout and skeleton

If no skeleton is given, a default {"type": "meta.context"} skeleton will be used.
Example
```
const blueprint = new Blueprint({
  'arch.sw': 1,
  'hw.device-type': 1
}, {
  type: 'my-context',
  slug: '{{children.arch.sw.slug}}-{{children.hw.device-type.slug}}'
})
```
Overrides Contract.constructor
- Defined in blueprint.ts:70

Properties

`Protected`$raw

$raw: BlueprintObject

Methods

addChild

addChild(contract: Contract): this
Function
Parameters
- contract: Contract
  contract
Returns this
contract
Name
module:contrato.Contract#addChild

Throws
if the child cannot be nested: its type overlaps an existing child's type, one being a prefix of the other (e.g. adding sw.os.kernel under a contract that already holds sw.os), it has no slug to be keyed by, or its type is not a dotted path. Nothing is added in those cases.
Example
```
const contract = new Contract({ ... })
contract.addChild(new Contract({ ... }))
```
Inherited from Contract.addChild
- Defined in contract.ts:310

addChildren

addChildren(contracts?: Contract[]): this
Function
Parameters
- contracts: Contract[] = []
  contracts
Returns this
contract
Name
module:contrato.Contract#addChildren

Description
This is a utility method over .addChild().

Throws
if any child cannot be nested, see .addChild(). Nothing is added in that case; the contracts passed in are cloned, so they stay usable.
Example
```
const contract = new Contract({ ... })
contract.addChildren([
  new Contract({ ... }),
  new Contract({ ... }),
  new Contract({ ... })
])
```
Inherited from Contract.addChildren
- Defined in contract.ts:359

areChildrenSatisfied

areChildrenSatisfied(options?: { types?: Set<string> }): boolean
Function
Parameters
- Optionaloptions: { types?: Set<string> } = {}
  options
  - Optionaltypes?: Set<string>
    
    the types to consider (all by default)
Returns boolean
whether the children are satisfied
Name
module:contrato.Contract#areChildrenSatisfied
Example
```
const contract = new Contract({ ... })
contract.addChildren([ ... ])

if (contract.areChildrenSatisfied({
  types: new Set([ 'sw.arch' ])
})) {
  console.log('This contract has all sw.arch requirements satisfied')
}
```
Inherited from Contract.areChildrenSatisfied
- Defined in contract.ts:948

clone

clone(): Contract
Function
Returns Contract
- the contract clone
Name
module:contrato.Contract#toJSON
Example
```
const contract = new Contract({ ... })
const clone = contract.clone()
```
Inherited from Contract.clone
- Defined in contract.ts:1080

findChildren

findChildren(matcher: MatcherObject): Contract[]

Function

Parameters

matcher: MatcherObject
matcher contract

Returns Contract[]

children

Name

module:contrato.Contract#findChildren

Example

const contract = new Contract({ ... })
contract.addChildren([ ... ])

const children = contract.findChildren(Contract.createMatcher({
  type: 'sw.os',
  slug: 'debian'
}))

children.forEach((child) => {
  console.log(child)
})

getAllNotSatisfiedChildRequirements

getAllNotSatisfiedChildRequirements(options?: { types?: Set<string> }): any[]
Function
Parameters
- Optionaloptions: { types?: Set<string> } = {}
  options
  - Optionaltypes?: Set<string>
    
    the types to consider (all by default)
Returns any[]
list of unsatisfied requirements
Name
module:contrato.Contract#getAllNotSatisfiedChildRequirements
Example
```
const contract = new Contract({ ... })
contract.addChildren([ ... ])

console.log(contract.getAllNotSatisfiedChildRequirements({
  types: new Set([ 'sw.arch' ])
}))
```
Inherited from Contract.getAllNotSatisfiedChildRequirements
- Defined in contract.ts:970

getAllSlugs

getAllSlugs(): Set<string>

Function

Returns Set<string>

slugs

Name

module:contrato.Contract#getAllSlugs

Example

const contract = new Contract({
  type: 'hw.device-type',
  name: 'Raspberry Pi',
  slug: 'raspberrypi',
  aliases: [ 'rpi', 'raspberry-pi' ]
})

console.log(contract.getAllSlugs())
> Set { raspberrypi, rpi, raspberry-pi }

getCanonicalSlug

getCanonicalSlug(): string | undefined
Function
Returns string | undefined
slug - contract canonical slug or slug if canonical slug doesn't exist
Name
module:contrato.Contract#getCanonicalSlug
Example
```
const contract = new Contract({
  type: 'arch.sw',
  name: 'armv7hf',
  slug: 'armv7hf'
  canonicalSlug: 'raspberry-pi'
})

console.log(contract.getCanonicalSlug())
```
Inherited from Contract.getCanonicalSlug
- Defined in contract.ts:229

getChildByHash

getChildByHash(hash: string): Contract | undefined
Function
Parameters
- hash: string
  child contract hash
Returns Contract | undefined
child
Name
module:contrato.Contract#getChildByHash
Example
```
const contract = new Contract({ ... })
contract.addChildren([ ... ])

const child = contract.getChildByHash('xxxxxxx')

if (child) {
  console.log(child)
}
```
Inherited from Contract.getChildByHash
- Defined in contract.ts:401

getChildren

getChildren(options?: { types?: Set<string> }): Contract[]
Function
Parameters
- Optionaloptions: { types?: Set<string> } = {}
  options
  - Optionaltypes?: Set<string>
    
    children types (all by default)
Returns Contract[]
children
Name
module:contrato.Contract#getChildren
Example
```
const contract = new Contract({ ... })
const children = contract.getChildren({
  types: new Set([ 'arch.sw' ])
})

for (const child of children) {
  console.log(child)
}
```
Inherited from Contract.getChildren
- Defined in contract.ts:429

getChildrenByType

getChildrenByType(type: string): Contract[]
Function
Parameters
- type: string
  contract type
Returns Contract[]
children
Name
module:contrato.Contract#getChildrenByType
Example
```
const contract = new Contract({ ... })
contract.addChildren([ ... ])
const children = container.getChildrenByType('sw.os')

children.forEach((child) => {
  console.log(child)
})
```
Inherited from Contract.getChildrenByType
- Defined in contract.ts:461

getChildrenCombinations

getChildrenCombinations(
    options: {
        from?: number;
        to?: number;
        type: string;
        [index: string]: any;
    },
): Contract[][]

Function

Parameters

options: { from?: number; to?: number; type: string; [index: string]: any }
options
- [index: string]: any
- Optionalfrom?: number
  
  number of contracts per combination (from)
- Optionalto?: number
  
  number of contracts per combination (to)
- type: string
  
  contract type

Returns Contract[][]

combinations

Name

module:contrato.Contract#getChildrenCombinations

Description

Note that the client is responsible for evaluating that the combination of contracts is valid with regards to requirements, conflicts, etc. This function simply returns all the possible combinations without any further checks.

The combinations output by this function is a plain list of contracts from which you can create a contract, or any other application specific data structure.

Example

const contract = new Contract({ ... })
contract.addChildren([
  new Contract({
    name: 'Debian Wheezy',
    version: 'wheezy',
    slug: 'debian',
    type: 'sw.os'
  }),
  new Contract({
    name: 'Debian Jessie',
    version: 'jessie',
    slug: 'debian',
    type: 'sw.os'
  }),
  new Contract({
    name: 'Fedora 25',
    version: '25',
    slug: 'fedora',
    type: 'sw.os'
  })
])

const combinations = contract.getChildrenCombinations({
  type: 'sw.os',
  from: 2,
  to: 2
})

console.log(combinations)
> [
>   [
>     new Contract({
>       name: 'Debian Wheezy',
>       version: 'wheezy',
>       slug: 'debian',
>       type: 'sw.os'
>     }),
>     new Contract({
>       name: 'Debian Jessie',
>       version: 'jessie',
>       slug: 'debian',
>       type: 'sw.os'
>     })
>   ],
>   [
>     new Contract({
>       name: 'Debian Wheezy',
>       version: 'wheezy',
>       slug: 'debian',
>       type: 'sw.os'
>     }),
>     new Contract({
>       name: 'Fedora 25',
>       version: '25',
>       slug: 'fedora',
>       type: 'sw.os'
>     })
>   ],
>   [
>     new Contract({
>       name: 'Debian Jessie',
>       version: 'jessie',
>       slug: 'debian',
>       type: 'sw.os'
>     }),
>     new Contract({
>       name: 'Fedora 25',
>       version: '25',
>       slug: 'fedora',
>       type: 'sw.os'
>     })
>   ]
> ]

getChildrenCrossReferencedContracts

getChildrenCrossReferencedContracts(
options: { from: Contract; types: Set<string> },
): Contract[]

Function

Parameters

options: { from: Contract; types: Set<string> }
options
- from: Contract
  
  contract to resolve external contracts from
- types: Set<string>
  
  types to consider

Returns Contract[]

children cross referenced contracts

Name

module:contrato.Contract#getChildrenCrossReferencedContracts

Example

const contract = new Contract({ ... })

contract.addChildren([
  new Contract({
    type: 'arch.sw',
    slug: 'armv7hf',
    name: 'armv7hf'
  }),
  new Contract({
    type: 'sw.os',
    slug: 'raspbian',
    requires: [
      {
        or: [
          {
            type: 'arch.sw',
            slug: 'armv7hf'
          },
          {
            type: 'arch.sw',
            slug: 'rpi'
          }
        ]
      }
    ]
  }),
  new Contract({
    type: 'sw.stack',
    slug: 'nodejs',
    requires: [
      {
        type: 'arch.sw',
        slug: 'armv7hf'
      }
    ]
  })
])

const references = contract.getChildrenCrossReferencedContracts({
  from: contract,
  types: new Set([ 'arch.sw' ])
})

console.log(references)
> [
>   Contract {
>     type: 'arch.sw',
>     slug: 'armv7hf',
>     name: 'armv7hf'
>   }
> ]

getChildrenTypes

getChildrenTypes(): Set<string>
Function
Returns Set<string>
types
Name
module:contrato.Contract#getChildrenTypes
Example
```
const contract = new Contract({ ... })
contract.addChildren([ { ... }, { ... } ])
console.log(contract.getChildrenTypes())
```
Inherited from Contract.getChildrenTypes
- Defined in contract.ts:378

getNotSatisfiedChildRequirements

getNotSatisfiedChildRequirements(
contract: Contract,
options?: { types?: Set<string> },
): any[]

Function

Parameters

contract: Contract
child contract
Optionaloptions: { types?: Set<string> } = {}
options
- Optionaltypes?: Set<string>
  
  the types to consider (all by default)

Returns any[]

list of unsatisfied requirements

Name

module:contrato.Contract#getNotSatisfiedChildRequirements

Example

const contract = new Contract({ ... })
contract.addChildren([
  new Contract({
    type: 'sw.os',
    name: 'Debian Wheezy',
    version: 'wheezy',
    slug: 'debian'
  }),
  new Contract({
    type: 'sw.os',
    name: 'Fedora 25',
    version: '25',
    slug: 'fedora'
  })
])

const child = new Contract({
  type: 'sw.stack',
  name: 'Node.js',
  version: '4.8.0',
  slug: 'nodejs',
  requires: [
    {
      or: [
        {
          type: 'sw.os',
          slug: 'debian'
        },
        {
          type: 'sw.os',
          slug: 'fedora'
        }
      ]
    }
  ]
})

console.log(contract.getNotSatisfiedChildRequirements(child))

getReferencedContracts

getReferencedContracts(
options: { from: Contract; types: Set<string> },
): { [index: string]: Contract[] }
Function
Parameters
- options: { from: Contract; types: Set<string> }
  options
  - from: Contract
    
    contract to resolve external contracts from
  - types: Set<string>
    
    types to consider
Returns { [index: string]: Contract[] }
referenced contracts
Name
module:contrato.Contract#getReferencedContracts
Example
```
const universe = new Contract({ ... })
universe.addChildren([ ... ])

const contract = new Contract({ ... })
for (const reference of contract.getReferencedContracts({
  types: new Set([ 'arch.sw' ]),
  from: universe
})) {
  console.log(reference.toJSON())
}
```
Inherited from Contract.getReferencedContracts
- Defined in contract.ts:672

getReferenceString

getReferenceString(): string
Function
Returns string
reference string
Name
module:contrato.Contract#getReferenceString
Example
```
const contract = new Contract({
  type: 'arch.sw',
  name: 'armv7hf',
  slug: 'armv7hf'
})

console.log(contract.getReferenceString())
```
Inherited from Contract.getReferenceString
- Defined in contract.ts:271

getSlug

getSlug(): string | undefined
Function
Returns string | undefined
slug - contract slug
Name
module:contrato.Contract#getSlug
Example
```
const contract = new Contract({
  type: 'arch.sw',
  name: 'armv7hf',
  slug: 'armv7hf'
})

console.log(contract.getSlug())
```
Inherited from Contract.getSlug
- Defined in contract.ts:160

getType

getType(): string
Function
Returns string
type - contract type
Name
module:contrato.Contract#getType
Example
```
const contract = new Contract({
  type: 'arch.sw',
  name: 'armv7hf',
  slug: 'armv7hf'
})

console.log(contract.getType())
```
Inherited from Contract.getType
- Defined in contract.ts:250

getVersion

getVersion(): string | undefined
Function
Returns string | undefined
slug - contract version
Name
module:contrato.Contract#getVersion
Example
```
const contract = new Contract({
  type: 'sw.os',
  name: 'Debian Wheezy',
  version: 'wheezy',
  slug: 'debian'
})

console.log(contract.getVersion())
```
Inherited from Contract.getVersion
- Defined in contract.ts:139

hasAliases

hasAliases(): boolean

Function

Returns boolean

whether the contract has aliases

Name

module:contrato.Contract#hasAliases

Example

const contract = new Contract({
  type: 'hw.device-type',
  name: 'Raspberry Pi',
  slug: 'raspberrypi',
  aliases: [ 'rpi', 'raspberry-pi' ]
})

if (contract.hasAliases()) {
  console.log('This contract has aliases')
}

`Protected`hash

hash(): string
Protected Function
Returns string
the contract hash
Name
module:contrato.Contract#hash

Description
The hash is computed from the contract's raw object the first time it is requested, and cached on the Rust side afterwards. Operations that mutate the contract invalidate that cache, so the hash is recomputed on the next call.
Example
```
const contract = new Contract({ ... })
console.log(contract.hash())
```
Inherited from Contract.hash
- Defined in contract.ts:97

`Protected`interpolate

interpolate(): this
Protected Function
Returns this
contract instance
Name
module:contrato.Contract#interpolate

Throws
if a templated field interpolates to an invalid value, e.g. a slug template resolving to a string with a space. The contract is left untouched in that case.
Example
```
const contract = new Contract({ ... })
contract.interpolate()
```
Inherited from Contract.interpolate
- Defined in contract.ts:116

raw

raw(): ContractObject
Function
Returns ContractObject
the JSON content of the contract
Name
module:contrato.Contract#raw
Example
```
const contract = new Contract({ ... })
console.log(contract.raw())
```
Inherited from Contract.raw
- Defined in contract.ts:38

removeChild

removeChild(contract: Contract): this
Function
Parameters
- contract: Contract
  contract
Returns this
parent contract
Name
module:contrato.Contract#removeChild
Example
```
const contract = new Contract({ ... })

const child = new Contract({ ... })
contract.addChild(child)
contract.removeChild(child)
```
Inherited from Contract.removeChild
- Defined in contract.ts:331

reproduce

reproduce(contract: Contract): IterableIterator<Contract>
Function
Parameters
- contract: Contract
  contract
Returns IterableIterator<Contract>
- an iterable over the valid contexts
Name
module:contrato.Blueprint#reproduce

Description
This method will generate a set of contexts that consist of every possible valid combination that matches the blueprint layout. It uses depth first search to calculate the product of contract combinations and returns the results as an iterable. This allows to reduce the memory usage when dealing with a large universe of contracts.

Throws
while iterating, if a generated context is invalid, e.g. a skeleton slug template that interpolates to a value which is not a valid slug. The iterator cannot be resumed past the failure.
Example
```
const contract = new Contract({ ... })
contract.addChildren([ ... ])

const blueprint = new Blueprint({
  'hw.device-type': 1,
  'arch.sw': 1
})

const contexts = blueprint.reproduce(contract)
for (const context of contexts) {
  console.log(context.toJSON());
}
```
- Defined in blueprint.ts:147

satisfiesChildContract

satisfiesChildContract(
contract: Contract,
options?: { types?: Set<string> },
): boolean

Function

Parameters

contract: Contract
child contract
Optionaloptions: { types?: Set<string> } = {}
options
- Optionaltypes?: Set<string>
  
  the types to consider (all by default)

Returns boolean

whether the contract is satisfied

Name

module:contrato.Contract#satisfiesChildContract

Example

const contract = new Contract({ ... })
contract.addChildren([
  new Contract({
    type: 'sw.os',
    name: 'Debian Wheezy',
    version: 'wheezy',
    slug: 'debian'
  }),
  new Contract({
    type: 'sw.os',
    name: 'Fedora 25',
    version: '25',
    slug: 'fedora'
  })
])

const child = new Contract({
  type: 'sw.stack',
  name: 'Node.js',
  version: '4.8.0',
  slug: 'nodejs',
  requires: [
    {
      or: [
        {
          type: 'sw.os',
          slug: 'debian'
        },
        {
          type: 'sw.os',
          slug: 'fedora'
        }
      ]
    }
  ]
})

if (contract.satisfiesChildContract(child)) {
  console.log('The child contract is satisfied!')
}

toJSON

toJSON(): ContractObject
Function
Returns ContractObject
JSON object
Name
module:contrato.Contract#toJSON
Example
```
const contract = new Contract({ ... })
const object = contract.toJSON()
console.log(JSON.stringify(object))
```
Inherited from Contract.toJSON
- Defined in contract.ts:288

`Static`build

build(source: ContractObject): Contract[]

Function

Parameters

source: ContractObject
source contract

Returns Contract[]

built contracts

Static

Name

module:contrato.Contract.build

Example

const contracts = Contract.build({
  name: 'debian {{version}}',
  slug: 'debian',
  type: 'sw.os',
  variants: [
    { version: 'wheezy' },
    { version: 'jessie' },
    { version: 'sid' }
  ]
})

contracts.forEach((contract) => {
  if (contract instanceof Contract) {
    console.log('This is a built contract')
  }
})

Throws

if an expanded contract is invalid, e.g. a variant that completes a templated slug with an illegal value.

`Static`createMatcher

createMatcher(obj: MatcherObject): MatcherObject
Function
Parameters
- obj: MatcherObject
  the match criteria
Returns MatcherObject
matcher
Static

Name
module:contrato.Contract.createMatcher

Description
A matcher allows to search for child contracts by type, slug, version range and data. It is a plain object handed straight to the WASM boundary, where contrato::ContractMatcher validates it — matchers carrying fields other than type, slug, version and data are rejected there, at findChildren time.
Example
```
// find all child contracts with type `hw.device-type` and `data`
// containing `{arch: 'armv7hf'}`
mycontract.findChildren(Contract.createMatcher({
  type: 'hw.device-type',
  data: { arch: 'armv7hf' },
}));
```
Inherited from Contract.createMatcher
- Defined in contract.ts:1003

`Protected` `Static`fromWasm

fromWasm(inner: Contract): Contract
Parameters
- inner: Contract
Returns Contract
Inherited from Contract.fromWasm
- Defined in contract.ts:75

`Static`isEqual

isEqual(contract1: Contract, contract2: Contract): boolean
Function
Parameters
- contract1: Contract
  a contract
- contract2: Contract
  a contract
Returns boolean
whether the contracts are equal
Static

Name
module:contrato.Contract.isEqual
Example
```
const contract1 = new Contract({ ... })
const contract2 = new Contract({ ... })

if (Contract.isEqual(contract1, contract2)) {
  console.log('These contracts are equal')
}
```
Inherited from Contract.isEqual
- Defined in contract.ts:1026

Class Blueprint

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Blueprint

Name

Memberof

Description

Example

Properties

Protected$raw

Methods

addChild

Parameters

Returns this

Name

Throws

Example

addChildren

Parameters

Returns this

Name

Description

Throws

Example

areChildrenSatisfied

Parameters

Optionaltypes?: Set<string>

Returns boolean

Name

Example

clone

Returns Contract

Name

Example

findChildren

Parameters

Returns Contract[]

Name

Example

getAllNotSatisfiedChildRequirements

Parameters

Optionaltypes?: Set<string>

Returns any[]

Name

Example

getAllSlugs

Returns Set<string>

Name

Example

getCanonicalSlug

Returns string | undefined

Name

Example

getChildByHash

Parameters

Returns Contract | undefined

Name

Example

getChildren

Parameters

Optionaltypes?: Set<string>

Returns Contract[]

Name

Example

getChildrenByType

Parameters

Returns Contract[]

Name

Example

getChildrenCombinations

Parameters

[index: string]: any

Optionalfrom?: number

Optionalto?: number

`Protected`$raw

`Optional`types?: Set<string>

`Optional`types?: Set<string>

`Optional`types?: Set<string>

`Optional`from?: number

`Optional`to?: number

`Optional`types?: Set<string>

`Protected`hash

`Protected`interpolate