Fenzland

Promisify of NodeJS async API

2018-12-30T15:38:06+08:00

Introduction

　　 Promise is the core of the modern async programming. But the NodeJS is designed before the Promise. So its huge number of async APIs are base on callback. We cannot use them unless we change them promisive, or say promisify. A ideal way is ask Ryan Dahl to change the APIs. Returns a promise instead of throw an error when the callback is not given. But it’s bad to take him from focus on deno. So, we must do it ourselves.

　　 For the huge number, wrap them one by one is not a good plan. Use what, wrap what is not the best too. We need a general, and as light-weight as better way to make this.

　　 So I make this:

Declare

function Do( api, ...args )
{
	return new Promise(
		( resolve, reject, )=> api(
			...args,
			( err, response, )=> {
				if( err )
					reject( err, );
				else
					resolve( response, );
			},
		),
	);
}

function Promisify( module, )
{
	const cache= {};
	
	return new Proxy(
		module,
		{
			get( target, key, receiver, ){
				if(!( Reflect.has( target, key, ) ))
					return undefined;
				
				return cache[key] || (
					cache[key]= ( ...args )=> Do(
						Reflect.get( target, key, receiver, ),
						...args,
					)
				);
			},
		},
	);
}

Usage

// Do
const fs= require( 'fs', );


Do( fs.readFile, '/path/to/file', 'utf-8', ).then( /* ... */ );

await Do( fs.readdir, '/path/to/directory', );


// Promisify
const pfs= Promisify( fs );


pfs.readFile( '/path/to/file', 'utf-8', ).then( /* ... */ );

await pfs.readdir( '/path/to/directory', );

Designing Concept

　　 The async APIs of NodeJS follows a standard: no matter how many the parameters, the last parameter is the callback. And there are two parameters for callback. The first is the error or null, the second is the result. So the function “Do” designed. 　　 But the function “Do”, is not so comfortable for JS programmers. If we can access new APIs just like the old one, it’s better. For this purpose, we can use Proxy to intercept the accessing, and return the promisified API by the Do function. At the last, we cache the promisified API to avoid pfs.readFile !== pfs.readFile.

Using Git Index

2018-12-16T13:26:21+08:00

　　 An healthy git repository, is readable and tracable. We need fully clear what we commit. The Git Index, is what we need, just like a shopping cart. We pick goods(updates) from the shelves(work tree). Then push the cart(index) to cash register, and buy(commit) them. With the Git Index, we have ability to deal with a big heap of updates orderly.

Basic Commands

　　 There are three git commands for managing Git Index. They are add, reset and checkout.

add add updates from work tree to index
reset remove updates from index
checkout give up updates that not be added to index (cover updates in work tree by index) 　　 Both reset and checkout are multi-purpose. The command reset also can use to move current branch. And the command checkout also can use to move HEAD and checkout to the work tree. The difference is the parameter for the command. If the parameter is a commit(hash or branch, tag…), it’s for the branch and HEAD. If the parameter is a path, or there is no parameter, it’s for the index.

Meticulous operations: `--patch`

　　 Each of add, reset, checkout can run with option --patch, or -p in short. Git will iterate over the updates and let’s handle them one by one. You can run with paths as parameters to iterate over one file or several files, or just run with no parameter to iterate over all updates. Using there command with -p option is the best way currently to manage the Git Index. I name it 3Ps Sorcery.

　　 After run the command, we get a interactive interface like this:

diff --git a/index.md b/index.md
index 921ba51..1c0d98b 100644
--- a/index.md
+++ b/index.md
@@ -3,5 +3,5 @@
 
 
 layout: home
-list_title: foo
+list_title: bar
 ---
Stage this hunk [y,n,q,a,d,k,K,j,J,g,/,s,e,?]?

The last Line is different with different command:

add
Stage this hunk [y,n,q,a,d,k,K,j,J,g,/,s,e,?]? 

reset
Unstage this hunk [y,n,q,a,d,k,K,j,J,g,/,s,e,?]? 

checkout
Discard this hunk from worktree [y,n,q,a,d,k,K,j,J,g,/,s,e,?]?

　　 As we see, git show an update in the file index.md. And give us several operations y,n,q,a,d,k,K,j,J,g,/,s,e,?. What are they use for? By the first sight, I only know the ? provides helps. So we input ? Enter. We get the message:

`add`

y - stage this hunk
n - do not stage this hunk
q - quit; do not stage this hunk or any of the remaining ones
a - stage this hunk and all later hunks in the file
d - do not stage this hunk or any of the later hunks in the file
g - select a hunk to go to
/ - search for a hunk matching the given regex
j - leave this hunk undecided, see next undecided hunk
J - leave this hunk undecided, see next hunk
k - leave this hunk undecided, see previous undecided hunk
K - leave this hunk undecided, see previous hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
? - print help

`reset`

y - unstage this hunk
n - do not unstage this hunk
q - quit; do not unstage this hunk or any of the remaining ones
a - unstage this hunk and all later hunks in the file
d - do not unstage this hunk or any of the later hunks in the file
g - select a hunk to go to
/ - search for a hunk matching the given regex
j - leave this hunk undecided, see next undecided hunk
J - leave this hunk undecided, see next hunk
k - leave this hunk undecided, see previous undecided hunk
K - leave this hunk undecided, see previous hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
? - print help

`checkout`

y - discard this hunk from worktree
n - do not discard this hunk from worktree
q - quit; do not discard this hunk or any of the remaining ones
a - discard this hunk and all later hunks in the file
d - do not discard this hunk or any of the later hunks in the file
g - select a hunk to go to
/ - search for a hunk matching the given regex
j - leave this hunk undecided, see next undecided hunk
J - leave this hunk undecided, see next hunk
k - leave this hunk undecided, see previous undecided hunk
K - leave this hunk undecided, see previous hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
? - print help

　　 What’s a hugging heap of dazing stuffs! Don’t worry, just let’s reorder them:

handlers:
`y` yes       do (add/reset/give up);
`n` no        don't (add/reset/give up);
`a` all       do    for all in this file;
`d` don't     don't for all in this file;
`e` edit      see next section;
`s` split     some times, git will assume several updates as one, you can split it;

navigations (only works in a file):
`g` goto      goto the nth update, such as `g 1`，`g 2`, the number start with 1;
`/` search    just like searching in vim, less... It's convenient for a big file with lots of updates;
`j` next      next unprocessed;
`J` Next      next update;
`k` previous  previous unprocessed;
`K` Previous  previous update;

others:
`q` quit      quit；
`?` help      print help；

　　 We only need know y, n, s, q for basic using. For advanced using, we need know one more: e. For programmers, that’s enough. For dictionary keeper, or Webpack configuratician, navigations will be useful.

　　 In this section, we talk about the e. To begin the editing, we need an editor. Just like when you run commit without -m opiton, git will open vim or nano when you using e. And the text in the editor will like this:

# Manual hunk edit mode -- see bottom for a quick guide
@@ -20,4 +20,5 @@
 	><ul
 		><li>foo</li
-		><li>bar</li
+		><li>baz</li
+		><li>qux</li
 	></ul
# ---
# Here will be some manual text.

　　 Here is an update, we delete the line bar, and insert lines baz and qux. The line @@ ... @@ shows the line number and line counts before and after edit. And follows the content of update. The first character of each line is the line type, can be space, - or +. The space means this line is a normal line, a - for a deleted line, and an + for a new inserted line. Attention, this space is not indentation. If you use indent characters for indentation, here is a space at the first. If you use spaces instead of indentation, one more space each line.

　　 If you just quit the editor without edit anything, it’s just equal to press a y instead of e. If you recover the update, remove all + lines, change -s to spaces, it’s just equal to press a n instead of e. We can modify it as you like, but not all modifications are allowed.

　　 It’s easier to understand when we run add. Here is an example, if we make modifications like this:

 	><ul
-		><li>foo</li
+		><li>qux</li
 		><li>bar</li
+		><li>Baz</li
 	></ul

As we see, we don’t delete line bar, but delete line foo. And we edit line baz, and insert qux to another position. That’s not difficult. We’ll found that space lines and - lines can change to each others, but you can not modify their content; + lines can make any modifications, remove or insert anywhere when add.

　　 But when reset, it’s different. Oppositely, space lines and + lines can change to each others, but you can not modify their content; - lines can make any modifications, remove or insert anywhere when add. It’s confusing. So, example again. the same situation, let’s edit the text to this:

 	><ul
+		><li>foo</li
-		><li>Bar</li
+		><li>baz</li
 		><li>qux</li
-		><li>ET</li
 	></ul

To understand what will happen, we must using words like give up or cancel. We change line foo from space line to + line, means we cancel the adding of line foo, but the line foo is not added, it’s over there original, so it’s means delete the line foo in fact. We change line bar to line Bar, means don’t cancel the deleting of bar, but cancel deleting of line Bar. And means delete line bar and add line Bar in fact. At last, insert a line ET. If you still hard to get it, just assume + lines as - lines and - lines as + lines.

　　 On checkout, since the direction is same with reset, so reverse + and - too. What in the paper is abstract. For fully understand, you need try it by your self.

　　 There is a feature lack that, the add -p doesn’t with new files. However, reset -p dose. For the new files, you can use add filename then reset -p filename to add it with patching.

File level and global operations

　　 Usually, always check over what you change with -p is fine. But some times you need file level or global operations.

git add file add all updates in the file from work tree to index
git reset file remove all updates in the file from index
git checkout file give up all updates in the file that not be added to index (cover the file in work tree by index)
git add . add all updates from work tree to index
git reset remove all updates from index
git checkout give up all updates that not be added to index (cover all updates in work tree by index)

Imperfect ultimate weapon `add --interactive`

　　 There is another more fashion option --interactive on command git add, -i in short. By the name, this is a interactive interface too. It seems like this:

           staged     unstaged path
  1:    unchanged        +0/-1 TODO
  2:    unchanged        +1/-1 index.html

*** Commands ***
  1: status       2: update       3: revert       4: add untracked
  5: patch        6: diff         7: quit         8: help
What now>

It’s shows status above which like git status but more clear, and commands below. There are 8 commands shown, and a ? hidden:

1 status         show the main interface, usually for refresh
2 update         add files into index, just like `add file` but not work for new files
3 revert         remove files from index，just like `reset file`
4 add untracked  add new files into index
5 patch          like `add -p file`
6 diff           show what in the index
7 quit           quit
8 help           help, about commands
?                help, about the interface

You can just use the index or the first letter instead of full command.

　　 There are 5 core commands: u r a p d. Each of them leads to a second level interface， the command prompt change from > to >>. In this level, we can choose files with index or unique prefix of filename. Currently, it’s not support segmental matching, fuzzy matching or *, ? yet. Nor tab hints and input history. Wish they will be added in the future. For now, the index is enough. We can add a - before the index or file path, to remove adding, Type Enter to confirm the selection and type Enter again to take the action.

　　 The add --i bring us a great interface, we can play fluently, without repeating git status. On the mode, this is the ultimate weapon. But it’s an imperfect weapon. There are add file, reset file and add -p file within the add -i. But reset -p file, checkout file, checkout -p file are missing. So, for right now the best way is still the 3Ps Sorcery.

Git post-update for auto-deploy

2018-12-01T17:00:00+08:00

For web project or other server side project, we need auto-deploy. For this, we need run some scripts after we push the git commits. That’s why post-update here.

　　 If we put script file under git-dir/hooks/ and name it with post-update, and chmod -x for it. The file will run after we push some commits to the git repository. You can yous any scripting language you like, such as bush, python, ruby, julia, PHP, Node.js… Compiled as well of cause, but not as easy to read and edit as scripting languages.

#Example 0.

　　 For simple scripts, bash is convenient.

#!/bin/bash
git --work-tree=/path-to/project-dir/ checkout "`git rev-list --tags --max-count=1`" -f >/dev/null

This script will checkout the newest tag to the work directory. It’s frequently-used.

#Example 1.

　　 This is an example of Laravel project, so we using PHP.

#!/usr/bin/env php
<?php

$product_dir= '/path-to/project-dir/';
$test_dir= '/path-to/test-dir/';

switch( $argv[1] )
{
	case 'refs/heads/migrate':
		`git --work-tree=$test_dir checkout -f migrate`;
		`$test_dir/artisan migrate:fresh --seed`;
	
	case 'refs/heads/test':
		`git --work-tree=$test_dir checkout -f test`;
		`composer --working-dir=$product_dir dump-autoload`;
		`$product_dir/artisan migrate`;
	break;
	
	case 'refs/heads/composer':
		`git --work-tree=$test_dir checkout -f composer`;
		`composer --working-dir=$test_dir update`;
		`$test_dir/artisan vendor:publish --all`;
		`git --work-tree=$test_dir checkout -f test`;
		`composer --working-dir=$product_dir dump-autoload`;
		`$product_dir/artisan migrate`;
		
		`git --work-tree=$product_dir checkout -f composer`;
		`composer --working-dir=$product_dir update`;
		`$product_dir/artisan vendor:publish --all`;
	
	case 'refs/heads/product':
		`git --work-tree=$product_dir checkout -f "\`git rev-list --tags --max-count=1\`"`;
		`composer --working-dir=$product_dir dump-autoload`;
		`$product_dir/artisan migrate`;
		`$product_dir/artisan view:clear`;
		`$product_dir/artisan route:cache`;
	break;
}

　　 This time, we do different things according to different bushed branch. When test branch is pushed, we checkout it to the test directory, and apply the migrations of DB. When migrate branch is pushed, we refresh the DB of the test environment, When project branch is pushed, we checkout the newest tag to the project environment, then apply migrations and clear view cache and rebuild route cache.

#Example 2.

　　 Here is the deploy script of this blog, on ruby.

#!/usr/bin/env ruby

# import rugged (the git API for ruby base on libgit2), we need install it by gem first 
require 'rugged'

# import jekyll, install by gem too 
require 'jekyll'

git_repository= '/path-to/git-repository/'
project_dir= '/path-to/project-dir/'
web_root_dir= '/path-to/web_root_dir/'

repo= Rugged::Repository.new( git_repository, )

# get the list of git tag.
tags= repo.tags.map{ |tag| tag.target }

# build the walker from master 
walker= Rugged::Walker.new( repo, )
walker.push( repo.head.target, )

# walk back and find the newest tag in the master branch 
latest_tag= walker.find{ |commit| tags.include?(commit) }

# checkout this tag 
repo.workdir= project_dir
repo.checkout( latest_tag.oid, :strategy=>:force, )

# build the jekyll project 
config= Jekyll.configuration( { 'source'=>project_dir, 'distination'=>web_root_dir, }, )
site= Jekyll::Site.new( config, )
site.process

　　 Here we use API instead of CLI to access git. Maybe a little inconvenience than CLI, but the API is more powerful. The libgit2 is a great lib of git API, it support more than a dozen of languages and environments.

　　 Above examples are the deploy scripts of real using in my work. Share the code, and more to the point, share the line of thought. We hope to bring help.

Amazing CSS Variables

2018-11-26T20:12:21+08:00

　　 We eagerly need variables in CSS by long ages. Now, with build systems, we can use variables with Sass and Less. What CSS Variables will bring to us? Something Sass/Less never give us.

Dynamic

　　 The places of variables in Sass/Less, will token by constants after build. Therefore, you can not change them. They are not real variables. On the other hand, CSS Variables is real variables, you can change them by @media or JS.

Better Scope Role

　　 CSS Variables, also named Custom Properties, they don’t like variables in Sass/Less, but like normal CSS Properties. The scope of variables in Sass/Less is between a pair of {}. CSS Variables, however, like other CSS Properties, defined in CSSOM and bing to DOM with selector. and available in the DOM element and its children (and children of children, and children of children of children…). So the scope is depend on DOM tree. That’s impossible in Sass/Less.

Componentization and Custom Properties

button
{
	min-width: calc(var(--button-size, 1)*1rem);
	height: calc(var(--button-size, 1)*1rem);
}

body>main
{
	--button-size: 1.5;
}

　　 In this example, we set size of buttons with --button-size. If it’s undefined, use the default value 1. This rule apply on all <button>s in the page. And we set --button-size: 1.5 on selector body>main. So the variable will apply on <main> directly belongs to <body> and it’s children. As we see, height of the <button>s in this <main> will be 1.5rem, and the height of the <button>s outside will be 1rem.

　　 You may say, what? use a variable before declaring?

　　 Um, let’s think out side the box, the button {} as a function, and --button-size as the parameter. The function called on rendering of <button>, and the value defined on body>main pass in.

　　 This little example show the basic componentization. The <button> is a component with styles inside, and with some parameters. We keep not changing styles inside the box, but only change the parameters when use it. The CSS Variables becomes the properties of the component.

　　 It’s hard to make world ordered by this primitive componentization. Fortunately, we have Web Components.

Work with Web Components

　　 In Custom Elements, styles are stand alone with outside. But the CSS Variables can penetrate the boundary.

　　 Here is a example.

:host
{
	--button-size: 1.5;
}

button
{
	font-size: var(--font-size, 1rem);
	min-width: calc(var(--button-size)*1rem);
	height: calc(var(--button-size)*1rem);
}

　　 Here, we set size of buttons just like previous. And, we declare --button-size on the :host, but not --font-size. The difference is: the variable --font-size can be defined on any layer outside, but the --button-size must be defined on the custom element itself. We can use two ways on different scene. The way like --button-size, is the common way to defined a parameter of element. And the way like --font-size, can use to access global configurations.

Interaction with JS

　　 Here are the API of CSS properties (include Custom Properties) for JS.

style instanceof CSSStyleDeclaration;
/*
 * The style can be a style object of a DOM element：
 *   document.body.style
 *
 * And can be a CSS rule：
 *   document.styleSheets[0].cssRules[0].style
 *
 * Also can be a computed result (read only):
 *   getComputedStyle( element, )
 */

// get value of a CSS property, (always got a string, even the style is undefined)
const value= style.getPropertyValue( '--foo', );

// set a property (the value always be converted to a string)
style.setProperty( '--foo', value, );

// remove a property
style.removeProperty( '--foo', );

　　 This is the better way to access CSS properties then read or assign the properties of the style object.

// good
style.setProperty( 'z-index', '1', );
style.setProperty( 'float', 'left', );

// bad
style.zIndex= '1';
style.cssFloat= 'left';

　　 Here is a situation that we get the position of mouse by JS, and read the layout. Then make some calculations with JS. And set some value to styles. That’s dreadful, JS has a hand in the layout, break the separation of concerns. And when JS read the layout, unnecessary reflow will happen.

　　 Using CSS Variables, the problems solved perfectly. You just need to pass the position from JS to CSS Variables. And do nothing else in JS. In css, using calc() to take layout calculations. The separation of concerns is obeyed. Unnecessary reflows are prevented too.

Data Types

　　 In CSS, the basic data types are number(with unit), string, keyword, color and so on, and list, besides. All of them can be the type of CSS Variables.

.foo
{
	--an-int: 3;
	--a-float: 5.2;
	--with-unit: 80%;
	--a-color: white;
	--a-string: 'foobar';
	--a-keyword: left;
	--a-list: 1px 1px;
	--another-list: green , 1px;
	--more-another-list: 20% / 1em;
}

　　 You can combine them and calculate. You must pay attention to the unit when calculating. To the lists, you need assume , and / as elements of list just like 1px.

.foo
{
	/* basic using */
	z-index: var(--an-int);
	font-size: var(--a-float);
	width: var(--with-unit);
	color: var(--a-color);
	font-family: var(--a-string);
	float: var(--a-keyword);
	margin: var(--a-list);
	border-radius: var(--more-another-list);
	
	/* complex using */
	background-color: hsla(var(--an-int),var(--with-unit),calc(var(--an-int)*20%));
	box-shadow: var(--a-list) 5px var(--another-list) 2px 2px red;
	border-radius: 4px 4px 4px var(--more-another-list) 4px 4px 4px;
}

Work with Animation and Transition

　　 Unfortunately, there is no browser support transition of CSS Variables. We can only use animation and transition on normal CSS properties.

.foo
{
	--lightness: 80%;
	color: hsla(120,100%,var(--lightness));
	background-color: hsla(0,100%,var(--lightness));
	
	/* Not supported */
	transition:
		--lightness 500ms
	;
	
	/* Supported */
	transition:
		color 500ms
		,
		background-color 500ms
	;
}

.foo:hover
{
	--lightness: 50%;
}

　　 Therefore, some exciting idea cannot achieve. Such as change hue and lightness by different speed, change color of gradient background… Let’s just await for future.

Fenz Cube

2018-11-26T20:08:32+08:00

　　 Thanks for Three.js and WebGL.

　　 Here is the hyperlink: Fenz Cube.

　　 Fenz Cube is developed on JS, and using ES6, includes ES6 modules, and without Webpack。 So it cannot run on old browsers, such as IE, even FireFox、Edge and Chromium < 63. Supporting browsers are Chrome, Chromium, Safari, Opera, Chinese 360, QQ (with in Chromium 63+)。

　　 Fenz Cube support both PC and mobile. On PC client, click the faces to twist the cube. Left click for anticlockwise twists, and the right click for clockwise twists. With Shift, Ctrl and Alt, we can do more different twists. Drag the middle button to rotate the view, but not left or right button by default. That can prevent misoperations. However, if you don’t like this, you can configure it on settings. Your settings will store on your localStorage in your browser. So the program will remember your preference. There are some other settings, include some display settings. One of them is showing backside. Turn on it, you can see the backside of cube with out rotating the view. And you can click too twist the cube,

Web Component

　　 Now, Fenz Cube support Web Component. What you need to do is import the JS module, and use <fenz-cube> HTML tag wherever you like in your page.

The codes are：

<!-- import -->
<script type="module" src="https://mc.fenzland.com/fenz-cube.js"></script>

<!-- insert cube -->
<fenz-cube puzzle="https://mc.fenzland.com/puzzles/Cubic|0|1.js"></fenz-cube>