normalize 0.0.6

  • Readme
  • Changelog
  • Example
  • Installing
  • 65

MIT License PRs Welcome Star on GitHub Watch on GitHub

Normalize #

About #

This project allows for the normalization and denormalization of GraphQL Documents.

The normalize function creates a flat map of normalized documents and can be used to cache results of GraphQL queries. It traverses the GraphQL AST and only includes the fields specified in the GraphQL Document in the normalized results.

The normalize function only normalizes entities that include a __typename field and a valid ID.

IDs are determined by the following:

  1. If a TypePolicy is provided for the given type, it's TypePolicy.keyFields are used.
  2. If a dataIdFromObject funciton is provided, the result is used.
  3. The id or _id field (respectively) are used.

Features #

FeatureProgress
Fragments
Variables
Interface & Union types
Aliases
TypePolicys (see Apollo)

Usage #

Assuming we have the following query...

import 'package:gql/language.dart';
import 'package:gql/ast.dart';
import 'package:normalize/normalize.dart';

final DocumentNode query = parseString("""
    query TestQuery {
      posts {
        id
        __typename
        author {
          id
          __typename
          name
        }
        title
        comments {
          id
          __typename
          commenter {
            id
            __typename
            name
          }
        }
      }
    }
  """)

... and executing that query produces the following response data:

final Map<String, dynamic> data = {
  "posts": [
    {
      "id": "123",
      "__typename": "Post",
      "author": {"id": "1", "__typename": "Author", "name": "Paul"},
      "title": "My awesome blog post",
      "comments": [
        {
          "id": "324",
          "__typename": "Comment",
          "commenter": {"id": "2", "__typename": "Author", "name": "Nicole"}
        }
      ]
    }
  ]
};

We can then run our normalize function:

final Map<String, dynamic> normalizedMap = normalize(query: query, data: data);
print(normalized);

Which will produce the following normalized result:

{
  "Query": {
    "posts": [
      {"$ref": "Post:123"}
    ]
  },
  "Post:123": {
    "id": "123",
    "__typename": "Post",
    "author": {"$ref": "Author:1"},
    "title": "My awesome blog post",
    "comments": [
      {"$ref": "Comment:324"}
    ]
  },
  "Author:1": {"id": "1", "__typename": "Author", "name": "Paul"},
  "Comment:324": {
    "id": "324",
    "__typename": "Comment",
    "commenter": {"$ref": "Author:2"}
  },
  "Author:2": {"id": "2", "__typename": "Author", "name": "Nicole"}
}

If we later want to denormalize this data (for example, when reading from a cache), we can call denormalize on the normalizedMap from above. This will give us back the original data response object.

denormalize(query: query, normalizedMap: normalizedMap)

Limitations #

TypePolicy.keyFields and FieldPolicy.keyArgs currently only accept a flat list of Strings. Functions and nested lists of strings and are not yet supported. FieldPolicy.merge and FieldPolicy.read are also not yet supported.

Dependencies #

This library depends on the gql library.

Changelog #

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.0.6] - 2020-01-11

Changed #

  • use standart Json type
  • update gql dependency

[0.0.5] - 2020-01-01

Changed #

  • denormalize and denormalizeFragment now return null if there is a existing data with different variables in the map (they previously returned an empty object).

[0.0.4] - 2019-12-30

Added #

  • operationName parameter for multi-operation documents

[0.0.3] - 2019-11-19

Added #

  • normalizeFragment function
  • denormalizeFragment function

[0.0.2] - 2019-11-18

Added #

  • Optionally add typenames when denormalizing

[0.0.1] - 2019-11-14

Added #

  • Initial normalize and denormalize implementations 🚀
  • Support for variables
  • Support for fragments (definitions and inline)
  • Support for Apollo-style TypePolicies
  • Support for Aliases
  • Support for interface & union types
  • Tests (for all of the above)

example/README.md

Example #

TODO: Add Example

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  normalize: ^0.0.6

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:normalize/normalize.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
43
Health:
Code health derived from static analysis. [more]
86
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
65
Learn more about scoring.

We analyzed this package on Jan 19, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4

Health suggestions

Fix lib/src/helpers/field_name_with_arguments.dart. (-3.93 points)

Analysis of lib/src/helpers/field_name_with_arguments.dart reported 8 hints, including:

line 8 col 5: DO use curly braces for all flow control structures.

line 10 col 5: DO use curly braces for all flow control structures.

line 19 col 5: DO use curly braces for all flow control structures.

line 21 col 5: DO use curly braces for all flow control structures.

line 23 col 5: DO use curly braces for all flow control structures.

Fix lib/src/denormalizeFragment.dart. (-2.96 points)

Analysis of lib/src/denormalizeFragment.dart reported 6 hints, including:

line 44 col 5: DO use curly braces for all flow control structures.

line 54 col 5: DO use curly braces for all flow control structures.

line 58 col 5: DO use curly braces for all flow control structures.

line 80 col 7: DO use curly braces for all flow control structures.

line 82 col 7: DO use curly braces for all flow control structures.

Fix lib/src/normalizeFragment.dart. (-2.96 points)

Analysis of lib/src/normalizeFragment.dart reported 6 hints, including:

line 44 col 5: DO use curly braces for all flow control structures.

line 54 col 5: DO use curly braces for all flow control structures.

line 58 col 5: DO use curly braces for all flow control structures.

line 81 col 7: DO use curly braces for all flow control structures.

line 83 col 7: DO use curly braces for all flow control structures.

Fix additional 3 files with analysis or formatting issues. (-4.97 points)

Additional issues in the following files:

  • lib/src/helpers/resolve_root_typename.dart (4 hints)
  • lib/src/denormalize.dart (3 hints)
  • lib/src/normalize.dart (3 hints)

Maintenance suggestions

Package is pre-v0.1 release. (-10 points)

While nothing is inherently wrong with versions of 0.0.*, it might mean that the author is still experimenting with the general direction of the API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.2 <3.0.0
gql ^0.12.0 0.12.0
Transitive dependencies
charcode 1.1.2
collection 1.14.12
meta 1.1.8
path 1.6.4
source_span 1.6.0
term_glyph 1.1.0
Dev dependencies
test ^1.9.4