Skip to content
This repository has been archived by the owner on Aug 28, 2020. It is now read-only.

SettingGateway v2.1 #179

Merged
merged 90 commits into from Feb 25, 2018
Merged

SettingGateway v2.1 #179

merged 90 commits into from Feb 25, 2018

Conversation

kyranet
Copy link
Contributor

@kyranet kyranet commented Feb 9, 2018

Description of the PR

This PR aims to overhaul SettingGateway v2 to improve user intuitiveness and the experience of developers when they use said system.

This PR went very far and with the breaking changes, I'm happy to announce SettingGateway v2.1, much more powerful and easier to use than the former, SettingGateway v2. New guides for this system are available in the docs.

TODO

  • Update guides.
  • Update changelog.
  • Remove the type ConfigUpdateEntryMany (consistency).
  • SchemaFolder#getList review. Replaced to Configuration#list

Changes Proposed in this Pull Request (List new items in CHANGELOG.MD)

Added:

  • Added support for Configuration#reset(string[]); to reset multiple keys.
  • Added util.arraysEqual.
  • Added property Symbol.iterator to Schedule.
  • Added Gateway#toJSON() and GatewayDriver#toJSON().
  • Added GatewayDriver#register to be able to register new gateways without events (directly in your app.js).
  • Added util.getIdentifier as a replacement for the function validator.
  • Added SchemaFolder#keys(), SchemaFolder#values(), SchemaFolder#entries() and SchemaFolder#[@@iterator](). Identical to Map's respective methods.

Changed:

  • [BREAKING] Refactored Configuration's internals for maximum consistency and reduced code duplication.
  • Changed the type for GatewayDriver#types from string[] to Set<string>.
  • Renamed SchemaPiece#modify() to SchemaPiece#edit().
  • Renamed Gateway#getKeys() and Gateway#getValues() to Gateway#keys(true) and Gateway#values(true) respectively, which return iterators.

Removed:

  • [BREAKING] Removed SchemaFolder#addKey and SchemaFolder#addFolder in favor to a more consistent Schema#add.
  • [BREAKING] Removed Configuration#resetConfiguration().
  • [PERF-MEM] Removed Configuration#type.
  • [BREAKING] Removed SchemaFolder#removeKey and SchemaFolder#removeFolder in favor to a more consistent Schema#remove.
  • Removed SchemaFolder#getList and replaced it to Configuration#list.
  • Removed the ConfigUpdateEntryMany typedef in favor of a more constant type.
  • Removed the resolver functions from constants.
  • Removed SchemaFolder#keys (Map<string>) to reduce RAM usage and key caching duplication.
  • Removed SettingGateway function validators.
  • Removed Collection cache provider (will be moved to klasa-pieces).

Fixed:

  • Fixed Util.deepClone not cloning full objects.
  • Fixed SchemaFolder#_shardSyncSchema not passing the action as string.
  • Fixed null values in updateMany's pattern not updating nested keys plus individual queries.
  • Fixed update/reset methods in Configuration not emitting configEntryCreate when the entry does not exist.
  • [Critical Fix] Fixed the updateMany pattern in Configuration not accepting a guild.
  • [Critical Fix] Fixed the configUpdateEntry event (used to sync configuration instances across shards) running in non-sharded bots, now it will be disabled if the bot is not sharded.
  • Fixed Configuration._patch not patching after the second nested folder.
  • Fixed SettingResolver's return types.
  • Fixed Gateway syncing keys even when it's unused.

Semver Classification

  • This PR only includes documentation or non-code changes.
  • This PR fixes a bug and does not change the (intended) framework interface.
  • This PR adds methods or properties to the framework interface.
  • This PR removes or renames methods or properties in the framework interface.

@kyranet kyranet added Type: Enhancement Issues and PRs related to feature enhancement. Meta: Refactor Issues and PRs related to refactors. labels Feb 9, 2018
@kyranet kyranet self-assigned this Feb 9, 2018
@kyranet kyranet requested a review from bdistin February 9, 2018 11:35
@kyranet kyranet added the Status: WIP Issues and PRs that are still a work in progress. label Feb 9, 2018
Copy link

@asmahood asmahood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requested changes marked in example

Things marked in example should just be removed

msg.guild.configs.update('roles.administrator', '339943234405007361', msg.guild);

// Updating an array
// userBlacklist, as mentioned in another tutorial, it's a piece with an array or users. Using
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

array of users not or

// Ensuring the function call adds (error if it exists)
msg.guild.configs.update('userBlacklist', '272689325521502208', { action: 'add' });

// Ensuring the function call removes (error if it not exists)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

error if it doesn't exist


| Name | Type | Description |
| :-----------------: | :------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| **any** | Anything, no type restriction | Resolves anything, even objects, the usage of this type will make a key unconfigurable |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolves anything, even objects. The usage of this type will make a key unconfigurable


## Adding new types

To add new keys, you use an {@link Extendable} extending {@link SettingResolver}. If you don't know how to create an extendable, check the following tutorial: {@tutorial CreatingExtendables}. The following extendable is a template for this:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To add new types, not keys, since the title is Adding new types


A schema works like a diagram or a blueprint, in SettingGateway, the schema defines the keys present in the configuration for a specific gateway. This feature serves multiple purposes:

1. Define what keys does the {@link Gateway} manage and their properties.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Define what keys does the {@link Gateway} manages and their properties.


## Adding folders

Folder creation is very similar to key creation, but with one key difference: it has no options for itself, but instead, it can create its children keys (like you can add a box with another boxes and pieces, into another). You can add a new key inside a new folder in two different ways:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(just like you can add a box with other boxes and pieces, into another)

}
```

> **Reminder**: To access to a key inside a folder in your configuration command, you use the access operator (`.`). For example: *k!conf set channels.modlogs #modlogs*
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To access to a key inside a folder


## Ensuring the existence of a key.

In [Klasa-Pieces](https://github.com/dirigeants/klasa-pieces/), specially, some pieces require a key from the configuration to work, however, the creator of the pieces does not know if the user who downloads the piece has it, so this function becomes useful in this case.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In Klasa-Pieces [REMOVE THE COMMA] especially,

@@ -0,0 +1,67 @@
# Understanding Schema's Keys

As mentioned in the previous tutorial, {@tutorial UnderstandingSchema}, SettingGateway's schema is divided in two parts: **folders** and **pieces**. Pieces are contained into folders, but it cannot have keys nor folders, instead, this holds the key's metadata such as its type, if it's configurable by the configuration command... you can check more information in the documentation: {@link SchemaPiece}.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I said in Discord, calling items in the schema as **folders** and **pieces** and also calling commands, events, extendables, inhibitors 'pieces' as well might be confusing to new users

Pieces are contained in folders, but they cannot have keys nor folders. [PERIOD] Instead .....

## Change the *provider's engine*.

For example, let's say I have downloaded the *rethinkdb* provider and I want to work with it, then we go to your main script file (`app.js`, `bot.js`..., wherever you declare the new Klasa.Client), and write the following code:
Now... how we update it? Go to your main file, where {@link KlasaClient} is initialized, and add a new option to your {@link KlasaClientOptions}. The following code snippet as an example:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now... how do we update it?

Copy link

@asmahood asmahood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amazing 👍

@kyranet
Copy link
Contributor Author

kyranet commented Feb 10, 2018

With the last commit, I could not find any other bug. Feel free to test more the latest changes, it should be working perfectly now.

@kyranet kyranet removed the Status: WIP Issues and PRs that are still a work in progress. label Feb 10, 2018
@vladfrangu
Copy link
Contributor

vladfrangu commented Feb 23, 2018

From the breaker of discord.js and klasa, who managed to cause a rewrite of SG,
The Seal of Approval

@kyranet kyranet removed the Status: WIP Issues and PRs that are still a work in progress. label Feb 24, 2018
@bdistin bdistin merged commit 0bd3d4f into master Feb 25, 2018
@bdistin bdistin deleted the SettingGateway-Refactor branch February 25, 2018 13:19
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Meta: BugFix PRs that fix bugs or issues. Meta: Error Handling Issues and PRs related to error handling. Meta: Refactor Issues and PRs related to refactors. Type: Caching Issues and PRs related to caching. Type: Enhancement Issues and PRs related to feature enhancement. Type: Performance Issues and PRs related to the performance of the framework's interface.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants