feat: new getItem() signature (#79)

Author: cyrilletuzi

CHANGELOG.md

@@ -4,19 +4,20 @@ This lib is fully documented and so you'll find detailed [migration guides](./MI
 
 ## 8.0.0-beta.3 (2019-02-07)
 
+**A [full migration guide to version 8](./docs/MIGRATION_TO_V8.md) is available.**
+
 ### Features
 
+- The schema used for validation can (and should) be passed directly as the second argument fo `getItem()`
 - The returned type of `getItem()` is now inferred for basic types (`string`, `number`, `boolean`)
-and arrays of basic types (`string[]`, `number[]`, `boolean[]`).
-- Just use the new `JSONSchema` interface, IntelliSense will adjust itself based on the `type` option.
+and arrays of basic types (`string[]`, `number[]`, `boolean[]`)
+- Just use the new `JSONSchema` interface, IntelliSense will adjust itself based on the `type` option
 - `indexedDB` database and object store names default values are exported and can be changed
 (see the [interoperability guide](./docs/INTEROPERABILITY.md))
 - `indexedDB` storage will now works in web workers too
 
 ### Breaking changes
 
-A [full migration guide to version 8](./docs/MIGRATION_TO_V8.md) is available.
-
 - `type` now required for array, object, const and enums validation schemas
 - `setItem()` and `setItemSubscribe()` no longer accept `null` or `undefined` when in `--strictNullChecks`
 - `JSONSchemaNull` removed
@@ -26,6 +27,7 @@ A [full migration guide to version 8](./docs/MIGRATION_TO_V8.md) is available.
 ### Non-breaking changes
 
 - `JSONSchemaNumeric` deprecated
+- `LSGetItemsOptions` deprecated (not necessary anymore)
 
 ### Reduced public API
 

README.md

@@ -127,13 +127,10 @@ If you tried to store `undefined`, you'll get `null` too, as some storages don't
 
 Don't forget it's client-side storage: **always check the data**, as it could have been forged or deleted.
 
-Starting with *version 5*, you can use a [JSON Schema](http://json-schema.org/) to validate the data.
-
-**Starting with *version 7*, validation is now required.**
-A [migration guide](./docs/MIGRATION_TO_V7.md) is available.
+You can use a [JSON Schema](http://json-schema.org/) to validate the data. **Starting with *version 7*, validation is now required.**
 
 ```typescript
-this.localStorage.getItem('test', { schema: { type: 'string' } })
+this.localStorage.getItem('test', { type: 'string' })
 .subscribe((user) => {
   // Called if data is valid or null
 }, (error) => {

docs/MIGRATION_TO_V7.md

@@ -83,7 +83,13 @@ So you ended up with a `string` type while the real data may not be a `string` a
 
 If you were not already validating your data, there are several options.
 
-### Solution 1: JSON schema validation (recommended)
+### Solution 1: JSON schema validation with v8 (recommended)
+
+Version 8 of the lib greatly simplifies validation. So if you're not yet on v7,
+we strongly recommend you to to [upgrade to v8 directly](./MIGRATION_TO_V8.md),
+and to follow the [new validation guide](./VALIDATION.md) instead.
+
+### Solution 2: JSON schema validation with v7 (quite painful)
 
 The simpler and better way to validate your data is to search `getItem` in your project 
 and **use the JSON schema option proposed by the lib**. For example:
@@ -96,9 +102,9 @@ this.localStorage.getItem<string>('test', { schema: { type: 'string' } })
 });
 ```
 
-**A [full validation guide](./VALIDATION.md) is available with all the options.**
+**A [full validation guide](./VALIDATION_BEFORE_V8.md) is available with all the options.**
 
-### Solution 2: custom validation (painful)
+### Solution 3: custom validation (very painful)
 
 You can use all the native JavaScript operators and functions to validate. For example:
 
@@ -138,7 +144,7 @@ this.localStorage.getItem('test').subscribe((unsafeResult) => {
 });
 ```
 
-### Solution 3: defer the upgrade (temporary)
+### Solution 4: defer the upgrade (temporary)
 
 **Version 6 of the library is compatible with Angular 7.**
 So you can upgrade to Angular 7 now and defer the upgrade of this lib,
@@ -147,7 +153,7 @@ to have some extra time to add validation.
 Of course, it should be a temporary solution as this scenario is *not* heavily tested,
 and as you'll miss new features and bug fixes.
 
-### Solution 4: no validation (dirty)
+### Solution 5: no validation (dirty)
 
 In some special scenarios, like development-only code,
 it could be painful to manage validation.
@@ -163,6 +169,6 @@ as this method as been flagged as deprecated.
 ## More documentation
 
 - [Full changelog for v7](../CHANGELOG.md)
-- [Full validation guide](./VALIDATION.md)
+- [Full validation guide](./VALIDATION_BEFORE_V8.md)
 - [Other migration guides](../MIGRATION.md)
 - [Main documentation](../README.md)

docs/MIGRATION_TO_V8.md

@@ -24,6 +24,7 @@ npm install @ngx-pwa/local-storage@next
 ```
 
 2. Start your project: problems will be seen at compilation.
+Or you could search for `getItem` as most breaking changes are about its options.
 
 ## The bad part: breaking changes
 
@@ -41,12 +42,17 @@ Also, `JSONSchemaNull` is removed.
 
 Before v8, `type` was optional:
 ```typescript
-this.localStorage.getItem('test', { schema: { items: { type: 'string' } } })
+this.localStorage.getItem('test', { schema: {
+  items: { type: 'string' }
+} })
 ```
 
 Since v8:
 ```typescript
-this.localStorage.getItem('test', { schema: { type: 'array', items: { type: 'string' } } })
+this.localStorage.getItem('test', {
+  type: 'array',
+  items: { type: 'string' }
+})
 ```
 
 Also, `items` no longer accepts an array of JSON schemas, meaning arrays with multiple types
@@ -58,16 +64,21 @@ are no longer possible (and it's better for consistency, use an object if you mi
 
 Before v8, `type` was optional:
 ```typescript
-this.localStorage.getItem('test', { schema: { properties: {
-  test: { type: 'string' }
-} } })
+this.localStorage.getItem('test', { schema: {
+  properties: {
+    test: { type: 'string' }
+  }
+} })
 ```
 
 Since v8:
 ```typescript
-this.localStorage.getItem('test', { schema: { type: 'object', properties: {
-  test: { type: 'string' }
-} } })
+this.localStorage.getItem('test', {
+  type: 'object',
+  properties: {
+    test: { type: 'string' }
+  }
+})
 ```
 
 ### Validation of constants
@@ -82,7 +93,7 @@ this.localStorage.getItem('test', { schema: { const: 'value' } })
 
 Since v8:
 ```typescript
-this.localStorage.getItem('test', { schema: { type: 'string', const: 'value' } })
+this.localStorage.getItem('test', { type: 'string', const: 'value' })
 ```
 
 Also, `JSONSchemaConst` interface is removed.
@@ -99,7 +110,7 @@ this.localStorage.getItem('test', { schema: { enum: ['value 1', 'value 2'] } })
 
 Since v8:
 ```typescript
-this.localStorage.getItem('test', { schema: { type: 'string', enum: ['value 1', 'value 2'] } })
+this.localStorage.getItem('test', { type: 'string', enum: ['value 1', 'value 2'] })
 ```
 
 It also means enums of different types are no longer possible (and it's better for consistency).
@@ -119,15 +130,28 @@ While not recommended, you can still force it:
 this.localStorage.getItem('test', { schema: someSchema as any })
 ```
 
-
 ## The good part: simplication changes
 
-The following changes are not required. Previous code will still work,
-but **for new code, follow these new guidelines**.
+The following changes are not required but strongly recommended.
+**Previous code will still work**, but *for new code, follow these new guidelines*.
+
+### Easier API for `getItem()`
+
+`getItem()` API has been simplified: the secong argument is now directly the schema for validation.
+
+Before v8:
+```typescript
+this.localStorage.getItem<string>('test', { schema: { type: 'string' } })
+```
+
+Since v8:
+```typescript
+this.localStorage.getItem('test', { type: 'string' })
+```
 
 ### Cast now inferred!
 
-The returned type of `getItem()` is now inferred for basic types (`string`, `number`, `boolean`)
+The previous change allows that the returned type of `getItem()` is now inferred for basic types (`string`, `number`, `boolean`)
 and arrays of basic types (`string[]`, `number[]`, `boolean[]`).
 
 Before v8:
@@ -143,21 +167,21 @@ this.localStorage.getItem<string>('test', { schema: { type: 'string' } }).subscr
 
 Since v8:
 ```typescript
-this.localStorage.getItem('test', { schema: { type: 'string' } }).subscribe((data) => {
+this.localStorage.getItem('test', { type: 'string' }).subscribe((data) => {
   data; // string :D
 });
 ```
 
-Cast is still needed for objects. Follow the [validation guide](./VALIDATION.md).
+Cast is still needed for objects. Follow the new [validation guide](./VALIDATION.md).
 
 ### Use the generic `JSONSchema`
 
-Now the `JSONSchema` interface has been refactored, just use this one,
-and avoid the specific ones (`JSONSchemaString`, `JSONSchemaBoolean` and so on).
+Now the `JSONSchema` interface has been refactored, just use this one.
 IntelliSense will adjust itself based on the `type` option.
+The specific interfaces (`JSONSchemaString`, `JSONSchemaBoolean` and so on) are still there but useless.
 
 `JSONSchemaNumeric` still works but is deprecated in favor of `JSONSchemaNumber` or `JSONSchemaInteger`
-(but again, just use `JSONSchema`)
+(but again, just use `JSONSchema`).
 
 ## More documentation