@balena/contrato - npm Package Compare versions

Comparing version 0.11.0-build-capability-support-b2e71c992182a8cf3bd9e0d3c1bfa3025e63b604-1 to 0.11.0-build-capability-support-c1afe4e8666d300324afa0cff3108680c3b77108-1

package.json

 {
   "name": "@balena/contrato",
-  "version": "0.11.0-build-capability-support-b2e71c992182a8cf3bd9e0d3c1bfa3025e63b604-1",
+  "version": "0.11.0-build-capability-support-c1afe4e8666d300324afa0cff3108680c3b77108-1",
   "description": "The official contract implementation",
@@ -74,4 +74,4 @@ "homepage": "https://github.com/product-os/contrato",
   "versionist": {
-    "publishedAt": "2024-12-30T14:04:57.188Z"
+    "publishedAt": "2025-01-03T02:16:14.400Z"
   }
 }

README.md

 # Contrato
 
-> The official contracts implementation
+The official [contracts](#about-contracts) implementation
 
-[![Documentation](https://github.com/product-os/contrato/actions/workflows/docs.yml/badge.svg)](https://balena-io.github.io/contrato/modules/contrato.html)
+## Quickstart
 
+```ts
+import { Contract } from 'contrato';
+
+const osContract = new Contract({
+	type: 'sw.os',
+	slug: 'balenaos',
+	version: '6.1.2',
+	children: [
+		{ type: 'sw.service', slug: 'balena-engine', version: '20.10.43' },
+		{ type: 'sw.service', slug: 'NetworkManager', version: '0.6.0' },
+	],
+	provides: [{ type: 'sw.feature', slug: 'secureboot' }],
+});
+
+const serviceContract = new Contract({
+	type: 'sw.application',
+	slug: 'myapp',
+	requires: [
+		{ type: 'sw.service', slug: 'balena-engine', version: '>20' },
+		{ type: 'sw.feature', slug: 'secureboot' },
+	],
+});
+
+if (osContract.satisfiesChildContract(serviceContract)) {
+	console.log('myapp can be installed!');
+}
+```
+
+[![Documentation](https://github.com/balena-io/contrato/actions/workflows/docs.yml/badge.svg)](https://balena-io.github.io/contrato/modules/contrato.html)
+
+## About contracts
+
+### What is a contract?
+
+Is a specification for describing _things_. A thing can be pretty much anything, a software library, a feature, an API, etc. Relationships between things can be established via composition and referencing (`requires` and `provides`). Through this library, contracts can be validated, composed and combined.
+
+### Why build this?
+
+balena.io is a complex product with a great number of inter-conecting components. Each of the components have their own requisites, capabilities, and incompatibilities. Contracts are an effort to formally document those interfaces, and a foundation on which we can build advanced tooling to ultimately automate the process of the team, increase productivity, and remove the human element from tasks that can be performed better by a machine.
+
+The concept of contracts is generic enough that it can be applied to seemingly unrelated scenarios, from base images and OS images, to device types and backend components. Re-using the same contract "format" between them allows us to multiply the gains we get by developing complex contract-related programming modules.
+
+### What can I do with contracts? Give me some examples
+
+Describe a _thing_ via a contract
+
+```json
+{
+	"type": "sw.library",
+	"slug": "glibc",
+	"version": "2.40",
+	"assets": {
+		"license": {
+			"name": "GNU Lesser General Public License",
+			"url": "https://www.gnu.org/licenses/lgpl-3.0.html#license-text"
+		}
+	}
+}
+```
+
+Describe a _thing_ that requires a _thing_
+
+```json
+{
+	"type": "sw.utility",
+	"slug": "curl",
+	"version": "8.11.1",
+	"requires": [{ "type": "sw.library", "slug": "glibc", "version": ">=2.17" }],
+	"data": {
+		"protocols": ["HTTP", "HTTPS", "FTP"]
+	}
+}
+```
+
+Describe a complex _thing_ via a composite contract
+
+```json
+{
+	"type": "sw.os",
+	"slug": "balenaos",
+	"version": "4.1.5",
+	"children": [
+		{
+			"type": "sw.library",
+			"slug": "glibc",
+			"version": "2.16",
+			"assets": {
+				"license": {
+					"name": "GNU Lesser General Public License",
+					"url": "https://www.gnu.org/licenses/lgpl-3.0.html#license-text"
+				}
+			}
+		}
+	]
+}
+```
+
+Validate requirements of a contract via [contrato](https://github.com/balena-io/contrato)
+
+```ts
+import { Contract } from 'contrato';
+
+const osContract = new Contract({
+	type: 'sw.os',
+	slug: 'balenaos',
+	version: '4.1.5',
+	children: [
+		{
+			type: 'sw.library',
+			slug: 'glibc',
+			version: '2.16',
+		},
+	],
+});
+
+const curlContract = new Contract({
+	type: 'sw.utility',
+	slug: 'curl',
+	version: '8.11.1',
+	requires: [{ type: 'sw.library', slug: 'glibc', version: '>=2.17' }],
+});
+
+if (osContract.satisfiesChildContract(curlContract)) {
+	console.log('cURL requirements are met and it can be installed!');
+} else {
+	// cannot install cURL, missing requirements: { type: 'sw.library', slug: 'glibc', version: '>=2.17' }
+	console.log(
+		'cannot install cURL, missing requirements: ',
+		osContract.getNotSatisfiedChildRequirements(curlContract),
+	);
+}
+```
+
+Describe a universe of _things_
+
+```ts
+import { Contract, Universe } from 'contrato';
+
+const universe = new Universe();
+universe.addChildren([
+	new Contract({ type: 'sw.os', slug: 'debian' }),
+	new Contract({ type: 'sw.os', slug: 'fedora' }),
+	new Contract({
+		type: 'arch.sw',
+		slug: 'armv7hf',
+		requires: [{ type: 'hw.device-type', data: { arch: 'armv7hf' } }],
+	}),
+	new Contract({
+		type: 'arch.sw',
+		slug: 'amd64',
+		requires: [{ type: 'hw.device-type', data: { arch: 'amd64' } }],
+	}),
+	new Contract({
+		type: 'hw.device-type',
+		slug: 'raspberrypi3',
+		data: { arch: 'armv7hf' /* ... */ },
+	}),
+	new Contract({
+		type: 'hw.device-type',
+		slug: 'intel-nuc',
+		data: { arch: 'amd64' /* ... */ },
+	}),
+]);
+```
+
+Generate combinations of _things_ with a Blueprint
+
+```ts
+import { Contract, Universe, Blueprint } from 'contrato';
+
+const universe = new Universe();
+universe.addChildren([
+	/* ... */
+]);
+
+const blueprint = new Blueprint(
+	{ 'hw.device-type': 1, 'arch.sw': 1, 'sw.os': 1 },
+	{ type: 'meta.context' },
+);
+
+// Generate contexts with valid combinations of the given types
+const contexts = blueprint.reproduce(universe);
+```
+
+Build templates using the metadata from a combination
+
+````ts
+import { Contract, Universe, Blueprint, buildTemplate } from 'contrato';
+
+/* ... */
+
+// Generate contexts with valid combinations of the given types
+const contexts = blueprint.reproduce(universe);
+const template = ```
+Welcome to {{this.sw.os.slug}}OS for {{this.hw.device-type.slug}}!
+
+This build supports the architecture {{this.arch.sw.slug}}
+```;
+
+for (const context of contexts) {
+	// Welcome to OS fedoraOS for intel-nuc
+	// ...
+	console.log(buildTemplate(template, context));
+}
+````
+
+### Additional information
+
+See [contracts specification](balena-contracts.md) for additional documentation on the contract format.
+
 ## Tests
@@ -8,0 +218,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

128739

increased by4.45%

Number of lines in readme file

245

increased by600%

No dependency changes