npm package: @juzi/wechaty-puppet
Description: Abstract Puppet for Wechaty
Author: Huan LI
Latest version: 1.0.132

# wechaty-puppet

[![Powered by Wechaty](https://img.shields.io/badge/Powered%20By-Wechaty-blue.svg)](https://wechaty.js.org)
[![NPM Version](https://badge.fury.io/js/wechaty-puppet.svg)](https://www.npmjs.com/package/wechaty-puppet)
[![npm (tag)](https://img.shields.io/npm/v/wechaty-puppet/next.svg)](https://www.npmjs.com/package/wechaty-puppet?activeTab=versions)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)
[![Linux/Mac Build Status](https://travis-ci.com/wechaty/wechaty-puppet.svg?branch=master)](https://travis-ci.com/wechaty/wechaty-puppet)
[![ES Modules](https://img.shields.io/badge/ES-Modules-brightgreen)](https://github.com/Chatie/tsconfig/issues/16)

![chatie puppet](https://wechaty.github.io/wechaty-puppet/images/puppet-logo.jpg)

> Picture Credit: [https://www.shareicon.net](https://www.shareicon.net/puppet-marionette-puppeteer-puppet-variant-marionette-variant-665400)

Abstract(Base) Class of Puppet Providers for Wechaty Framework.

This module is part of the [Wechaty](https://github.com/wechaty/wechaty) Framework SDK.

Learn more at:

1. Wiki: <https://github.com/wechaty/wechaty/wiki/Puppet>
1. Issue: <https://github.com/wechaty/wechaty/issues/1167>

## Documentation

Wechaty Puppet Provider Interface Documentation can be found at <https://wechaty.github.io/wechaty-puppet/typedoc/classes/puppet.html>

> Automatica Generated by [TypeDoc](http://typedoc.org/)

## Example

PuppetMock: <https://github.com/wechaty/wechaty-puppet-mock>

The above puppet provider is just for mocking and easy to understand. It will be a good starter when you want to develope a new puppet by yourself for fullfil your need, for example, connect Wechaty with Wechat Official Account.

### Providers

* [PuppetPadchat](https://github.com/lijiarui/wechaty-puppet-padchat) iPad API via Protocol Server, created by [@lijiarui](https://github.com/lijiarui)
* [PuppetIoscat](https://github.com/linyimin-bupt/wechaty-puppet-ioscat) iPhone App Hook API, created by [@linyimin-bupt](https://github.com/linyimin-bupt)
* [PuppetWechat4u](https://github.com/wechaty/wechaty-puppet-wechat4u) Web API via HTTP, created by [@huan](https://github.com/huan)
* [PuppetPuppeteer](https://github.com/wechaty/wechaty-puppet-puppeteer) Web API via Browser, created by [@huan](https://github.com/huan)
* [PuppetService](https://github.com/wechaty/wechaty-puppet-service) gRPC Proxy via Chatie.io(PaaS - Puppets as a Service), created by [@huan](https://github.com/huan)

## Dependencies

1. `FileBox` (npm module `file-box`) MUST be imported from `wechaty-puppet` because all the Wechaty Framework needs to check `instanceof FileBox`, we must be sure all `FileBox` is the same version.
2. `MemoryCard` (npm module `memory-card`) MUST be imported from `wechaty-puppet` because all the Wechaty Framework needs to check `instanceof MemoryCard`, we must be sure all `MemoryCard` is the same version.

## Peer Dependence

`Puppet`(npm module `wechaty-puppet`) itself must be a _peer Dependencies_ for all the Puppet Providers, and should only be installed via Wechaty because all Puppet Providers should share the same Puppet Base Class with Wechaty, we must be sure all `Puppet` is the same version.

## Wechaty Puppet Toolsets

### 1. Using SwitchState

You can get to know the puppet start/stop state from the `state` property:

1. `puppet.state.on() === 'pending'` will be true when the puppet is starting
2. `puppet.state.on() === true` will be true when the puppet is started
3. `puppet.state.off() === 'pending'` will be true when the puppet is stoping
4. `puppet.state.off() === true' will be true when the puppet is stopped

Learn more about the puppet.state at <https://github.com/huan/state-switch>

### 2. Using Brolog

Using Brolog to output necessary log messages.

#### 2.1 Get log from Brolog

```ts
import { log } from 'brolog'
```

#### 2.2 Log Format

```ts
log.verbose('ModuleName', 'methodName() Your Verbose Message Here')
log.silly('ModuleName', 'methodName() Your Silly Message Here')
```

#### 2.3 Log Level

Brolog has five log levels, it should be used and follow the following rules:

| Log Level | What does it means | Usage in Puppet |
| :---      | :---               | :---            |
| `log.silly()` | There's some detail debug information | Can be used in everywhere as you like |
| `log.verbose()` | There's some debug information | Should be used at the beginning of every method() |
| ~~`log.info()`~~ | ~~There's something we need to let user know~~ | ~~Should NEVER to be used because Puppet is Library~~ |
| `log.warn()` | There's a Coverable Error | **Should not be used** unless we have to |
| `log.error()` | There's a Un-covered Error | **Should not be used** unless we have to |

### 3. Using LRU Cache

Set the max size for wechaty entities in LRU Cache.

| Env Name | What does it means |
| :---     | :---               |
| `WECHATY_PUPPET_LRU_CACHE_SIZE_CONTACT` | The max cache size for contact, default value `3000` |
| `WECHATY_PUPPET_LRU_CACHE_SIZE_FRIENDSHIP` | The max cache size for friendship, default value `100` |
| `WECHATY_PUPPET_LRU_CACHE_SIZE_MESSAGE` | The max cache size for message, default value `500` |
| `WECHATY_PUPPET_LRU_CACHE_SIZE_ROOM` | The max cache size for room, default value `500` |
| `WECHATY_PUPPET_LRU_CACHE_SIZE_ROOM_INVITATION` | The max cache size for room invitation, default value `100` |
| `WECHATY_PUPPET_LRU_CACHE_SIZE_ROOM_MEMBER` | The max cache size for room member, default value `30000` |

## Resources

### Pure Function

* [Functional Programming Concepts: Pure Functions](https://hackernoon.com/functional-programming-concepts-pure-functions-cafa2983f757)
* [What Are Pure Functions And Why Use Them?](https://medium.com/@jamesjefferyuk/javascript-what-are-pure-functions-4d4d5392d49c)
* [Master the JavaScript Interview: What is a Pure Function?](https://medium.com/javascript-scene/master-the-javascript-interview-what-is-a-pure-function-d1c076bec976)

### Mixin

* [The mixin pattern in TypeScript – all you need to know](https://www.bryntum.com/blog/the-mixin-pattern-in-typescript-all-you-need-to-know/)
* [Mixin Classes in TypeScript](https://mariusschulz.com/blog/mixin-classes-in-typescript)

## History

### master v1.0 - Initial Release

### v0.49 (Oct 2021)

1. ~~Add `Error` interface to `EventErrorPayload`, and make `.data` optional~~
2. Using [Mixin](https://en.wikipedia.org/wiki/Mixin) to extend `Puppet`

### v0.43 (Aug 28, 2021)

1. Support ES Modules

### v0.16 (Sep 2019)

Works with the following Puppet Providers:

1. wechaty-puppet-puppeteer
1. wechaty-puppet-padchat
1. wechaty-puppet-mock
1. wechaty-puppet-wechat4u

### v0.0.1 (Jun 2018)

1. Define the Abstract Puppet Layer for Wechaty
1. Seperate code from Wechaty

## Author

[Huan LI](https://github.com/huan) ([李卓桓](http://linkedin.com/in/zixia)) zixia@zixia.net

[![Profile of Huan LI (李卓桓) on StackOverflow](https://stackexchange.com/users/flair/265499.png)](https://stackexchange.com/users/265499)

## Copyright & License

* Code & Docs © 2018-now Huan LI \<zixia@zixia.net\>
* Code released under the Apache-2.0 License
* Docs released under Creative Commons