Merge pull request #92 from septs/master

improve typescript typing

index.d.ts

@@ -1,24 +1,63 @@
-declare class Hasher {
-    constructor(size?: 224 | 256 | 384 | 512);
+declare class Hasher<S = number> {
+    constructor(size?: S);
 
     update(data: Buffer): this;
     update(data: string, encoding?: BufferEncoding): this;
 
     digest(): Buffer;
     digest(encoding: "binary"): Buffer;
     digest(encoding: BufferEncoding): string;
+    digest(options: DigestOptions<"binary">): Buffer;
+    digest(options: DigestOptions<BufferEncoding>): string;
 
     reset(): this;
 }
 
-export class SHA3 extends Hasher {
-    static SHA3Hash: typeof Hasher;
+declare interface DigestOptions<T> {
+    format: T;
+    buffer?: Buffer;
+    padding?: number;
 }
 
-export const SHA3Hash: typeof Hasher;
-
-export const Keccak: typeof Hasher;
+/**
+ * The SHA-3 specification requires that the input message be appended with a
+ * two-bit suffix, `01`. For byte-aligned messages, this results in an extra
+ * `0x02` byte (bits fill in from the right).
+ *
+ * Then, the standard Keccak padding scheme is applied (pad10*1), placing an
+ * additional bit at the `0x04` position, resulting in `0x06`.
+ *
+ * https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf, Section B.2
+ */
+export class SHA3<S extends 224 | 256 | 384 | 512 = 512> extends Hasher<S> {
+    /**
+     * For backwards-compatibility, sprinkle SHA3Hash into the default export.
+     *
+     * @deprecated
+     */
+    static SHA3Hash: typeof Keccak;
+}
 
-export const SHAKE: typeof Hasher;
+/**
+ * Provided for historical purposes. This is an alias for the *Keccak* algorithm,
+ * which an early version of SHA3 with different padding.
+ *
+ * @deprecated
+ */
+export const SHA3Hash: typeof Keccak;
+
+/**
+ * The Keccak reference implementation uses the simplest possible padding scheme,
+ * described as follows:
+ *
+ * > Definition 1. Multi-rate padding, denoted by pad10*1, appends a single bit 1
+ * > followed by the minimum number of bits 0 followed by a single bit 1 such that
+ * > the length of the result is a multiple of the block length.
+ *
+ * https://keccak.team/files/Keccak-reference-3.0.pdf, Section 1.1.2
+ */
+export class Keccak<S extends 224 | 256 | 384 | 512 = 512> extends Hasher<S> {}
+
+export class SHAKE<S extends 128 | 256 = 256> extends Hasher<S> {}
 
 export default SHA3;

src/index.js

@@ -1,7 +1,7 @@
 import { Buffer } from 'buffer';
 import Sponge from './sponge';
 
-const createHash = ({ allowedSizes, padding }) => function Hash(size = 512) {
+const createHash = ({ allowedSizes, defaultSize, padding }) => function Hash(size = defaultSize) {
   if (!this || this.constructor !== Hash) {
     return new Hash(size);
   }
@@ -51,13 +51,13 @@ const createHash = ({ allowedSizes, padding }) => function Hash(size = 512) {
  * The Keccak reference implementation uses the simplest possible padding scheme,
  * described as follows:
  *
- * > Definition 1. Multi-rate padding, denoted by pad10\∗1, appends a single bit 1
+ * > Definition 1. Multi-rate padding, denoted by pad10*1, appends a single bit 1
  * > followed by the minimum number of bits 0 followed by a single bit 1 such that
  * > the length of the result is a multiple of the block length.
  *
  * @see {@link https://keccak.team/files/Keccak-reference-3.0.pdf}, Section 1.1.2
  */
-const Keccak = createHash({ allowedSizes: [224, 256, 384, 512], padding: 0x01 });
+const Keccak = createHash({ allowedSizes: [224, 256, 384, 512], defaultSize: 512, padding: 0x01 });
 
 /**
  * The SHA-3 specification requires that the input message be appended with a
@@ -69,9 +69,9 @@ const Keccak = createHash({ allowedSizes: [224, 256, 384, 512], padding: 0x01 })
  *
  * @see {@link https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf}, Section B.2
  */
-const SHA3 = createHash({ allowedSizes: [224, 256, 384, 512], padding: 0x06 });
+const SHA3 = createHash({ allowedSizes: [224, 256, 384, 512], defaultSize: 512, padding: 0x06 });
 
-const SHAKE = createHash({ allowedSizes: [128, 256], padding: 0x1F });
+const SHAKE = createHash({ allowedSizes: [128, 256], defaultSize: 256, padding: 0x1F });
 
 /**
  * Provided for historical purposes. This is an alias for the *Keccak* algorithm,