From 336a0ff9689b656d3c0be7817ba1bf8a814967a8 Mon Sep 17 00:00:00 2001 From: Patrick Stewart Date: Sun, 4 Aug 2024 01:04:01 -0700 Subject: [PATCH] update: working on project readme's --- README.md | 2 +- packages/auth/README.md | 40 +-------- packages/config/README.md | 40 +-------- packages/contracts/README.md | 40 +-------- packages/database/README.md | 40 +-------- packages/http/README.md | 40 +-------- packages/typeforge/README.md | 168 ++++++++++++++++++++++++++++------- 7 files changed, 144 insertions(+), 226 deletions(-) diff --git a/README.md b/README.md index ba9b972..8531658 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

+

## About Protevus diff --git a/packages/auth/README.md b/packages/auth/README.md index 8b55e73..757f4c9 100644 --- a/packages/auth/README.md +++ b/packages/auth/README.md @@ -1,39 +1 @@ - - -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. - -## Features - -TODO: List what your package can do. Maybe include images, gifs, or videos. - -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. - -```dart -const like = 'sample'; -``` - -## Additional information - -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +

\ No newline at end of file diff --git a/packages/config/README.md b/packages/config/README.md index 8b55e73..757f4c9 100644 --- a/packages/config/README.md +++ b/packages/config/README.md @@ -1,39 +1 @@ - - -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. - -## Features - -TODO: List what your package can do. Maybe include images, gifs, or videos. - -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. - -```dart -const like = 'sample'; -``` - -## Additional information - -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +

\ No newline at end of file diff --git a/packages/contracts/README.md b/packages/contracts/README.md index 8b55e73..757f4c9 100644 --- a/packages/contracts/README.md +++ b/packages/contracts/README.md @@ -1,39 +1 @@ - - -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. - -## Features - -TODO: List what your package can do. Maybe include images, gifs, or videos. - -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. - -```dart -const like = 'sample'; -``` - -## Additional information - -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +

\ No newline at end of file diff --git a/packages/database/README.md b/packages/database/README.md index 8b55e73..757f4c9 100644 --- a/packages/database/README.md +++ b/packages/database/README.md @@ -1,39 +1 @@ - - -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. - -## Features - -TODO: List what your package can do. Maybe include images, gifs, or videos. - -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. - -```dart -const like = 'sample'; -``` - -## Additional information - -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +

\ No newline at end of file diff --git a/packages/http/README.md b/packages/http/README.md index 8b55e73..757f4c9 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -1,39 +1 @@ - - -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. - -## Features - -TODO: List what your package can do. Maybe include images, gifs, or videos. - -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. - -```dart -const like = 'sample'; -``` - -## Additional information - -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +

\ No newline at end of file diff --git a/packages/typeforge/README.md b/packages/typeforge/README.md index 8b55e73..03e8764 100644 --- a/packages/typeforge/README.md +++ b/packages/typeforge/README.md @@ -1,39 +1,147 @@ - +A library for encoding and decoding dynamic data into Dart objects. -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. +## Basic Usage -## Features - -TODO: List what your package can do. Maybe include images, gifs, or videos. - -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. +Data objects extend `Coding`: ```dart -const like = 'sample'; +class Person extends Coding { + String name; + + @override + void decode(KeyedArchive object) { + // must call super + super.decode(object); + + name = object.decode("name"); + } + + @override + void encode(KeyedArchive object) { + object.encode("name", name); + } +} ``` -## Additional information +An object that extends `Coding` can be read from JSON: + +```dart +final json = json.decode(...); +final archive = KeyedArchive.unarchive(json); +final person = Person()..decode(archive); +``` + +Objects that extend `Coding` may also be written to JSON: + +```dart +final person = Person()..name = "Bob"; +final archive = KeyedArchive.archive(person); +final json = json.encode(archive); +``` + +`Coding` objects can encode or decode other `Coding` objects, including lists of `Coding` objects and maps where `Coding` objects are values. You must provide a closure that instantiates the `Coding` object being decoded. + +```dart +class Team extends Coding { + + List members; + Person manager; + + @override + void decode(KeyedArchive object) { + super.decode(object); // must call super + + members = object.decodeObjects("members", () => Person()); + manager = object.decodeObject("manager", () => Person()); + } + + @override + void encode(KeyedArchive object) { + object.encodeObject("manager", manager); + object.encodeObjects("members", members); + } +} +``` + +## Dynamic Type Casting + +Types with primitive type arguments (e.g., `List` or `Map`) are a particular pain point when decoding. Override `castMap` in `Coding` to perform type coercion. +You must import `package:protevus_typeforge/cast.dart as cast` and prefix type names with `cast`. + +```dart +import 'package:protevus_typeforge/cast.dart' as cast; +class Container extends Coding { + List things; + + @override + Map> get castMap => { + "things": cast.List(cast.String) + }; + + @override + void decode(KeyedArchive object) { + super.decode(object); + + things = object.decode("things"); + } + + @override + void encode(KeyedArchive object) { + object.encode("things", things); + } +} + +``` + + +## Document References + +`Coding` objects may be referred to multiple times in a document without duplicating their structure. An object is referenced with the `$key` key. +For example, consider the following JSON: + +```json +{ + "components": { + "thing": { + "name": "The Thing" + } + }, + "data": { + "$ref": "#/components/thing" + } +} +``` + +In the above, the decoded value of `data` inherits all properties from `/components/thing`: + +```json +{ + "$ref": "#/components/thing", + "name": "The Thing" +} +``` + +You may create references in your in-memory data structures through the `Coding.referenceURI`. + +```dart +final person = Person()..referenceURI = Uri(path: "/teams/engineering/manager"); +``` + +The above person is encoded as: + +```json +{ + "$ref": "#/teams/engineering/manager" +} +``` + +You may have cyclical references. + +See the specification for [JSON Schema](http://json-schema.org) and the `$ref` keyword for more details. -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more.