otiai10 / chomex

Chrome Extension Messaging Routing Kit / Promisify Chrome Messaging / LocalStorage Object Mapper

chomex

Chrome Extension Messaging Routing Kit.

• Router to handle onMessage with routes expression
• Client to Promisify sendMessage
• Model to access to localStorage like ActiveRecord
• Types to define data schema of Model

Installation

npm install chomex

Why?

.onMessage like a server routing

👎 Dispatching message inside addListener function makes my code messy and unreeadable.

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  switch(message.action) {
  case "/users/get":
    GetUser.apply(sender, [message, sendResponse]);
    break;
  default:
    NotFound.apply(sender, [message, sendResponse]);
  }
  return true;
});

👍 chomex.Router makes it more claen and readable.

const router = new chomex.Router();
router.on("/users/get", GetUser);
chrome.runtime.onMessage.addListener(router.listener());

Happy 🤗

.sendMessage like a fetch client

👎 Handling the response of sendMessage by callback makes my code messy and unreadable.

chrome.runtime.sendMessage({action:"/users/get",id:123}, (response) => {
  if (response.status == 200) {
    alert("User: " + response.user.name);
  } else {
    console.log("Error:", response);
  }
});

👍 chomex.Client makes it clean and readable by handling response with Promise.

const client = new chomex.Client(chrome.runtime);
const response = await client.message("/users/get", {id:123});
alert("User: " + response.data.user.name);

Happy 🤗

Examples

NOTE: These examples are using async/await on top-level. I believe you are familiar with asyc/await.

background.js as a server

import {Router, Model, Types} from 'chomex';

// Define your model
class User extends Model {
  static schema = {
    name: Types.string.isRequired,
    age:  Types.number,
  }
}

const router = new Router();

// Define your routes
router.on("/users/create", message => {
  const obj = message.user;
  const user = User.new(obj).save();
  return user;
});

router.on("/users/get", message => {
  const userId = message.id;
  const user = User.find(userId);
  if (!user) {
    return {status:404,error:"not found"};
  }
  // You can also return async Promise
  return Promise.resolve(user);
});

// Of course, you can separate files
// in which controller functions are defined.
import {UserDelete} from "./Controllers/Users";
router.on("/users/delete", UserDelete);

// Don't forget to add listener to chrome modules.
chrome.runtime.onMessage.addListener(router.listener());

content_script.js as a client

import {Client} from 'chomex';

const client = new Client(chrome.runtime);

// it sends message to "/users/get" route.
const user = {name: 'otiai10', age: 30};
const response = await client.message('/users/create', {user});
console.log("Created!", response.data);

const {data: user} = await client.message('/users/get', {id: 12345});
console.log("Found:", res.data);

Customize Router for other listeners

You can also customize resolver for routing. It's helpful when you want to make routings for EventListener modules on chrome, such as chrome.notifications.onClicked, chrome.webRequest.onBeforeRequest or so.

// Resolver rule, which resolve given "id" to routing name.
const resolve = (id) => {
  const prefix = id.split(".")[0];
  return {name: prefix};
};

const router = new Router(resolve);
// You see, this controller is invoked when
// a notification with ID "quest.xxxx" is clicked.
router.on('quest', NotificaionOnClickController.Quest);

chrome.notifications.onClicked.addListener(router.listener());

For more information

• Router
• Client
• Model
• Types

Reference Projects

Projects using chomex

• otiai10/kanColleWidget: Route / Controller
• otiai10/chant: Model
• henry40408/awesome-stars: Router with async/await

chomex's Issues

Model.useStorage(Storage)

interface Sotrage {
    getItem(key: string): any
    setItem(key: string, value: any)
    removeItem(key: string)
}
Model.useStorage(Storage);

for example

const StoragePushEffort = {
    getItem: (key: string) => {
        fetch(`/data/${key}`).then(res => res.json()).then(json => {
            localStorage.setItem(key, json);
        });
        // it's available for next time
        return localStorage.getItem(key);
    },
    setItem: (key: string, value: string) => {
        localStorage.setItem(key, value);
        fetch(`/data/${key}`, {method:'POST', body: value})
    },
    removeItem: (key: string) => {
         localStorage.removeItem(key);
         fetch(`/data/${key}`, {method:'DELETE'})
    },
}
Model.useStorage(SotragePushEffort);

`Model.delete`

Model.list() doesn't consider "not-stored" entities even when default given.

class Foo extends chomex.Model {
    public static default = {
        "aa": {...},
        "bb": {...},
        "cc": {...},
    }
}

// As is
Foo.list(); // []

// To be
Foo.list(); // (3) [Foo, Foo, Foo]

Need `_id` in `Model.all` response

sequentialID bugs

all	next
{}	1
{1: {}}	2
{1: {}, 2:{}}	2

Is sending message to specific extension ID supported?

Model.schema

class User extends Model {
  static schema = {
    name: Model.string.isRequired
  }
}

new Client(chrome.runtime) does not work when executing content script via chrome.tabs.executeScript()

When running
this.client = new Client(chrome.runtime);
in the content script.
It works fine when injected Declaratively.

When using chrome.tabs.executeScript() to inject content script, it throws exception:

Uncaught (in promise) TypeError: Cannot read property 'sendMessage' of undefined
at new Client

transformer for Router

given

declare function OnTabUpdatedListenerFunction(tabId: number, info: TabInfo, tab: Tab): void;
chrome.tabs.onUpdated.addListener(fn);

want

const resolver = (tabId: number, info: TabInfo, tab: Tab): Routing => {
    return {name: "foobar"}
}
const transformer = (tabId: number, info: TabInfo, tab: Tab): Message => {
    // ...
}
const router = new Router(resolver, transformer);

so that

router.on("foobar", (message: Message) => {
    // do what I want
});
chrome.tab.onUpdated.addListener(router.listener());

includes

• Refactor the types of Message and Routing as TypeScript

No need to be Regex match for SerialRouter

it's enough to be perfect matching

https://github.com/otiai10/chomex/blob/master/src/Router/index.js#L101

"routing not found for "undefined""

weird

Model.list

Model.all() == dictionary
Model.list() == []

alias: Model.filter(() => true)

Model.sync

Set up logic to sync

import {Model} from "chomex";

// {{{ It really depends on you!!
const mySyncFunc = (_model) => {
    const dict = JSON.parse(window.localStorage.getItem(_model.name));
    // but I recommend to return Promise object ;)
    return new Promise(resolve => chrome.storage.sync.set({[_model.name]:dict}, resolve));
};
// }}}

Model.setSyncFunc(mySyncFunc);

Sync specific model

class User extends chomex.Model {}

document.querySelector("button#sync").addEventListener("onclick", () => {
    User.sync().then(() => alert("Synced!!"));
});

500 without error message when Controller function doesn't return any response

Related: https://github.com/otiai10/chomex/blob/master/src/Router/Router.js#L143-L153

Types.date

stored as a string, decoded as Date class

sequential next id

chomex/src/Model/index.js

Lines 118 to 120 in c28ba4d

	static nextID(/* TODO: generate next ID with regarding all entities */) {
	return String(Date.now());
	}

on sending message to a runtime on which NO LISTENER added

Error in event handler for (unknown): TypeError: Cannot read property 'status' of undefined
    at TargettedClient../node_modules/chomex/lib/Client/index.js.Client._finally (chrome-extension://mbhfjahbokpmoabjfinclaingicjddpc/dest/js/background.js:246:40)
    at defaultCallback (chrome-extension://mbhfjahbokpmoabjfinclaingicjddpc/dest/js/background.js:223:23)

client raises error

Uncaught Error: Attempting to use a disconnected port object

Problem

It's known that this is caused by trying sendResponse to no-longer-exsting or explicitly-closed runtime port.

Idea

It's better Controller can specify that it doesn't want to sendResponse, explicitly.

for example,

const FooController = (message) => {
    // ...

    // return nothing
    // otherwise, `return;`
};

As is

Controllers with returning nothing are handled as error cases here

if (typeof response == 'undefined') {
    sendResponse(this._formatResponse({
        status: 500, // TODO: should it be 500?
        message: `\`${controllerFunc.name || '(anonymous controller)'}\`: Response should be defined. ex) return true;`,
    }));
    return true;
}

To be

if (typeof response == 'undefined') {
    /*
    sendResponse(this._formatResponse({
        status: 500, // TODO: should it be 500?
        message: `\`${controllerFunc.name || '(anonymous controller)'}\`: Response should be defined. ex) return true;`,
    }));
    */
    return true;
}

`Not Found` for simple GET request

contents_page

import {Client} from 'chomex';
const client = new Client(chrome.runtime, true);
client.message('/foo/bar').catch(err => {
    console.log(err);
});

• AS IS
  • {status: 404, message: "routing not found for undefined"}
• SHOULD BE
  • {status: 404, message: "routing not found for /foo/bar"}

Client.connect(tab.id).message("/foo/bar")

To enable to have long-live connection
https://developer.chrome.com/extensions/runtime#type-Port

const client = Client.connect(tab.id);
client.message("/foo/bar");