Updated documentation, fixed minor bugs (#24)

Author: ArtiomTr

README.md

@@ -22,157 +22,57 @@ yarn add pxth
 
 Here are all functions described.
 
-### toPxth
-
-Convert string / number / symbol to Pxth.
-
-Usage:
+### Pxth\<T>
 
+Holds path to field of type `T` in the origin object. 
 ```ts
-import { toPxth, ROOT_PATH } from 'pxth';
-
-toPxth('a.b.c'); // -> ['a', 'b', 'c']
+const a: Pxth<string>; // path to string field.
 
-// any symbol
-toPxth(Symbol()); // -> [Symbol()]
-// ROOT_PATH symbol
-toPxth(ROOT_PATH); // -> []
-
-toPxth(0); // -> [0]
+const b: Pxth<number>; // path to number field.
 ```
 
-### pxthToString
-
-Convert Pxth to string. Throws error if pxth cannot be stringified. [Here is function for check](#canBeStringified)
-
-Usage:
-
+If `T` is object, it is possible to get paths to its fields:
 ```ts
-import { pxthToString } from 'pxth';
-
-pxthToString(['lol', 'b', 0, ' .as0 ']); // -> lol.b.0.[" .as0 "]
-
-pxthToString([Symbol(), 'asdf']); // -> throws error
-```
+const objectPath: Pxth<{ inner: string }>; // path to parent object.
 
-### stringToPxth
+const innerPath: Pxth<string> = objectPath.inner; // path to object's field.
 
-Convert string to pxth. Function [toPxth](#toPxth) calls it, if first argument is string.
+const lengthPath: Pxth<number> = innerPath.length; // you can do it also for primitive type fields.
 
-```ts
-import { stringToPxth } from 'pxth';
-
-stringToPxth('hello.a.b'); // -> ['hello', 'a', 'b']
+const deepLengthPath: Pxth<number> = objectPath.inner.length; // any amount of levels, just like normal object.
 ```
 
-### get
+### deepGet
 
 Deeply get value from object.
 
 Usage:
 
 ```ts
-import { get } from 'pxth';
-
-get({ a: { b: { c: 'Hello world!' } } }, toPxth('a.b.c')); // -> 'Hello world'
-
-// third argument is default value
-get({ a: 'hello' }, toPxth('b.c.d'), 'Default value'); // -> 'Default value'
-```
-
-### set
-
-Deeply set value in object. Mutates the object and returns it. If value already exists, overwrites it.
-
-Usage:
-
-```ts
-import { set } from 'pxth';
-
-set({ a: { hello: 'asdf' } }, toPxth('a.hello'), 'New value'); // -> { a: { hello: 'New value' } }
-
-set({ a: 'hello' }, toPxth('a.b'), 'New value'); // -> { a: { b: 'New value' } }
-```
-
-### isNestedPath
-
-Determines if one path is child path of another.
-
-Usage:
-
-```ts
-import { isNestedPath } from 'pxth';
-
-isNestedPath(['hello', 'bye', 'yes'], ['hello']); // -> true
-
-isNestedPath(['hello', 'bye', 'yes'], ['hello', 'bye', 'no']); // -> false
-```
-
-### longestCommonPath
+import { deepGet } from 'pxth';
 
-Returns longest common path in array
-
-Usage:
+const somePath: Pxth<string> = /* from somewhere */;
 
-```ts
-import { longestCommonPath } from 'pxth';
+// Function is type safe - type of value will be automatically inferred from Pxth. In this case - string.
+const value = deepGet({ a: { b: { c: 'Hello world!' } } }, somePath);
 
-longestCommonPath([
-    ['hello', 'a'],
-    ['hello', 'b'],
-    ['hello', 'c'],
-]); // -> ['hello']
+console.log(value); // -> 'Hello world'
 
-longestCommonPath([['a'], ['b'], ['c']]); // -> []
 ```
 
-### canBeStringified
-
-Function, detecting if `Pxth` instance could be stringified or not.
-
-Usage:
-
-```ts
-import { canBeStringified } from 'pxth';
-
-canBeStringified(['hello', 'world']); // -> true
+### deepSet
 
-canBeStringified([Symbol(), 'asdf']); // -> false
-```
-
-### relativePath
-
-Make one path relative to another
-
-Usage:
-
-```ts
-import { relativePath } from 'pxth';
-
-relativePath(['hello', 'world'], ['hello', 'world', 'asdf']); // -> ['asdf']
-relativePath(['a', 'b', 'c'], ['a', 'b', 'c', 'd', 'e']); // -> ['d', 'e']
-relativePath(['a'], ['b']); // -> Error
-```
-
-### toObjectKey
-
-Convert pxth to object key
+Deeply set value in object. Mutates the object and returns it. If value already exists, overwrites it.
 
 Usage:
 
 ```ts
-import { toObjectKey } from 'pxth';
+import { deepSet } from 'pxth';
 
-toObjectKey(['a', 'b', 'c']); // -> 'a.b.c'
-toObjectKey([]); // -> ROOT_PATH
-```
+const somePath: Pxth<string> = /* from somewhere */;
 
-### ROOT_PATH
-
-Constant, used in [toObjectKey](#toObjectKey) function, to convert empty Pxth to object key.
-
-```ts
-import { ROOT_PATH } from 'pxth';
+// Type safe - type of third parameter is inferred from Pxth.
+deepSet({ a: { hello: 'asdf' } }, somePath, 'New value'); // -> { a: { hello: 'New value' } }
 ```
 
 ## Contributing

src/Pxth.ts

@@ -1,25 +1,29 @@
-type OmitMethods<V extends object> = Pick<
+type OmitMethods<V> = Pick<
     V,
     {
         [K in keyof V]: V[K] extends Function ? never : K;
     }[keyof V]
 >;
 
-type RecordPxth<V extends object> = {
+type RecordPxth<V> = {
     [K in keyof OmitMethods<V>]: Pxth<V[K]>;
 };
 
-type ArrayPxth<V extends unknown[]> = {
-    [K in number]: Pxth<V[number]>;
-} &
-    RecordPxth<Omit<V, number>>;
+type PreparePxth<V> = V extends number
+    ? Number
+    : V extends boolean
+    ? Boolean
+    : V extends string
+    ? String
+    : V extends symbol
+    ? Symbol
+    : V;
 
-type ObjectPxth<V extends object> = V extends unknown[]
-    ? ArrayPxth<V>
-    : RecordPxth<V>;
+type SpecificPxth<V> = V extends unknown[]
+    ? RecordPxth<Omit<Array<V>, number>>
+    : {};
 
 declare const BrandKey: unique symbol;
-declare const PrimitiveKey: unique symbol;
 
 export type Pxth<V> = {
     /**
@@ -30,15 +34,5 @@ export type Pxth<V> = {
      * assign value, that cannot be accessed (because BrandKey is not exported)
      */
     [BrandKey]: V;
-} & (V extends object
-    ? ObjectPxth<V>
-    : {
-          /**
-           * Another trick - if we leave this object empty, typescript will
-           * automatically unwrap all non-object types (Pxth<number> becomes
-           * { [BrandKey]: number }). Because of that, we cannot infer type
-           * when using in generic functions. To prevent this behavior, we
-           * add another inaccessible property.
-           */
-          [PrimitiveKey]: true;
-      });
+} & RecordPxth<PreparePxth<V>> &
+    SpecificPxth<V>;

src/PxthSource.ts src/PxthSegments.tssrc/PxthSource.ts renamed to src/PxthSegments.ts

@@ -1,6 +1,6 @@
 import { SegmentsToken } from './getPxthSegments';
 import { Pxth } from './Pxth';
-import { PxthSegments } from './PxthSource';
+import { PxthSegments } from './PxthSegments';
 
 const handlers: ProxyHandler<
     Record<string, Pxth<unknown>> & {

src/createPxthProxy.ts

@@ -1,4 +1,4 @@
-import { PxthSegments } from './PxthSource';
+import { PxthSegments } from './PxthSegments';
 import { Pxth } from '.';
 
 export const SegmentsToken = Symbol();

src/getPxthSegments.ts

@@ -2,7 +2,7 @@ export * from './deepGet';
 export * from './deepSet';
 export { getPxthSegments } from './getPxthSegments';
 export * from './Pxth';
-export * from './PxthSource';
+export * from './PxthSegments';
 export * from './RootPath';
 export * from './createPxth';
 export * from './pxthToString';

src/index.ts

@@ -1,7 +1,6 @@
 import { createPxth } from './createPxth';
 import { getPxthSegments } from './getPxthSegments';
 import { Pxth } from './Pxth';
-import { PxthSegments } from './PxthSource';
 
 /**
  * Finds longest common path.