feat: friendly path for records

Author: JesusTheHun

docs/src/guide/cluster-types.md

@@ -101,7 +101,11 @@ Cluster types support a few options that can be passed during their declaration.
 
 ```ts
 type ClusterTypesOptions = {
-  autocomplete?: 'strict' | 'friendly'; // default: 'friendly'
+  codeCompletion?: {
+    array?: 'friendly' | 'strict'; // default: 'friendly'
+    record?: 'friendly' | 'strict'; // default: 'friendly'
+    recordPlaceholder?: string; // default: '#'
+  };
   keyMatchingStrategy?: 'always' | 'firstMatch'; // default: 'always'
   keyDelimiter?: string;
 }
@@ -218,10 +222,10 @@ type MyClusterTypes = {
 };
 ```
 
-### Autocomplete
+### Code completion
 
-There is a limitation of TypeScript regarding autocomplete when the path is a template string like `authors[${number}]`, the autocomplete will not offer that value.  
-Because of that, Cbjs adds _friendly paths_ to the autocomplete list :
+There is a limitation of TypeScript regarding code completion when the path is a template string like `authors[${number}]`, the typescript service will not offer that value.  
+Because of that, Cbjs adds _friendly paths_ to the completion list :
 
 ```ts twoslash
 import { connect, DocDef } from '@cbjsdev/cbjs';
@@ -245,13 +249,16 @@ const cluster = await connect<MyClusterTypes>('');
 const collection = cluster.bucket('store').scope('library').collection('books');
 
 // ---cut-before---
-// @noErrors: 2769
+// @noErrors: 2345 2769
 const result = await collection
   .lookupIn('book::001')
   .get('autho');
 //           ^|
 ```
 
+&nbsp;  
+&nbsp;
+
 Because their length is fixed, all indexes will be offered for tuples.
 
 ```ts twoslash
@@ -276,7 +283,7 @@ const cluster = await connect<MyClusterTypes>('');
 const collection = cluster.bucket('store').scope('library').collection('books');
 
 // ---cut-before---
-// @noErrors: 2769
+// @noErrors: 2345 2769
 const result = await collection
   .lookupIn('book::001')
   .get('quater_sal');
@@ -286,9 +293,62 @@ const result = await collection
 &nbsp;  
 &nbsp;  
 &nbsp;  
-&nbsp;
+&nbsp;  
+&nbsp;  
+
+
+For records, a placeholder will be injected where the key is expected :
+
+```ts twoslash
+import { connect, DocDef } from '@cbjsdev/cbjs';
+
+type MyClusterTypes = {
+  store: {
+    library: {
+      books: [ DocDef<
+        `book::${string}`,
+        {
+          editions: Record<`edition::${string}`, { name: string; firstRelease: number }>
+        }
+      > ]
+    };
+  };
+};
+
+const cluster = await connect<MyClusterTypes>('');
+const collection = cluster.bucket('store').scope('library').collection('books');
+
+// ---cut-before---
+// @noErrors: 2345 2769
+const result = await collection
+  .lookupIn('book::001')
+  .get('edit');
+//          ^|
+```
 
-You can turn off friendly path in the cluster types options :
+&nbsp;  
+&nbsp;  
+&nbsp;  
+&nbsp;  
+
+::: tip
+Use specific key type such as `edition::${string}` instead of simply `string` to benefit from friendly paths.
+Wide type like `string` will match the placeholder and will be swallowed.
+:::
+
+To change the placeholder or turn off friendly path completely, set the options the cluster types definitions :
+
+```ts
+type MyClusterTypes = {
+  '@options': {
+    codeCompletion: {
+      array: 'strict'; // default 'friendly'
+      record: 'strict'; // default 'friendly'
+      recordPlaceholder: '!'; // default '#'
+    }
+  }
+};
+```
 
 ## Incremental adoption
 

docs/src/guide/features.md

@@ -81,7 +81,7 @@ type MyClusterTypes = {
 const cluster = await connect<MyClusterTypes>('');
 const collection = cluster.bucket('store').scope('library').collection('books');
 const bookId = 'book::001';
-// @noErrors: 2769
+// @noErrors: 2345 2769
 // ---cut-before---
 const {
   content: [title],

packages/cbjs/src/clusterTypes/clusterTypes.spec-d.ts

@@ -17,7 +17,6 @@ import { describe, expectTypeOf, it } from 'vitest';
 
 import {
   CollectionName,
-  CouchbaseClusterTypes,
   DefaultClusterTypes,
   IsDefaultClusterTypes,
   LookupInMacroShape,
@@ -34,7 +33,6 @@ import {
   CollectionContainingDocDef,
   CollectionMatchingDocDef,
   DocDef,
-  PathAutocomplete,
 } from './clusterTypes.js';
 import { LookupInGetPath } from './kv/lookup/lookupOperations.types.js';
 
@@ -363,78 +361,3 @@ describe('CollectionContainingDocBody', () => {
     >().toEqualTypeOf<Collection<UserClusterTypes, 'store', 'library', 'books'>>();
   });
 });
-
-describe('PathAutocomplete', () => {
-  type BookDocDef = DocDef<`book::${string}`, { metadata: { tags: string[] } }>;
-
-  it('should offer friendly paths as is when no options are provided', () => {
-    type ClusterTypesWithArrays = {
-      b: { s: { c: [BookDocDef] } };
-    };
-
-    type UserCollection = Collection<ClusterTypesWithArrays, 'b', 's', 'c'>;
-
-    expectTypeOf<
-      PathAutocomplete<UserCollection, Exclude<LookupInGetPath<BookDocDef>, ''>>
-    >().toEqualTypeOf<
-      | 'metadata'
-      | 'metadata.tags'
-      | `metadata.tags[${number}]`
-      | 'metadata.tags[]'
-      | LookupInMacroShape
-    >();
-  });
-
-  it('should offer friendly paths as is when options are set but no the autocomplete property', () => {
-    type ClusterTypesWithArrays = {
-      '@options': { keyMatchingStrategy: 'always' };
-      'b': { s: { c: [BookDocDef] } };
-    };
-
-    type UserCollection = Collection<ClusterTypesWithArrays, 'b', 's', 'c'>;
-
-    expectTypeOf<
-      PathAutocomplete<UserCollection, Exclude<LookupInGetPath<BookDocDef>, ''>>
-    >().toEqualTypeOf<
-      | 'metadata'
-      | 'metadata.tags'
-      | `metadata.tags[${number}]`
-      | 'metadata.tags[]'
-      | LookupInMacroShape
-    >();
-  });
-
-  it('should offer friendly paths as is when the option is set to friendly', () => {
-    type ClusterTypesWithArrays = {
-      '@options': { autocomplete: 'friendly' };
-      'b': { s: { c: [BookDocDef] } };
-    };
-
-    type UserCollection = Collection<ClusterTypesWithArrays, 'b', 's', 'c'>;
-
-    expectTypeOf<
-      PathAutocomplete<UserCollection, Exclude<LookupInGetPath<BookDocDef>, ''>>
-    >().toEqualTypeOf<
-      | 'metadata'
-      | 'metadata.tags'
-      | `metadata.tags[${number}]`
-      | 'metadata.tags[]'
-      | LookupInMacroShape
-    >();
-  });
-
-  it('should offer strict paths as is when the option is set to strict', () => {
-    type ClusterTypesWithArrays = {
-      '@options': { autocomplete: 'strict' };
-      'b': { s: { c: [BookDocDef] } };
-    };
-
-    type UserCollection = Collection<ClusterTypesWithArrays, 'b', 's', 'c'>;
-
-    expectTypeOf<
-      PathAutocomplete<UserCollection, Exclude<LookupInGetPath<BookDocDef>, ''>>
-    >().toEqualTypeOf<
-      'metadata' | 'metadata.tags' | `metadata.tags[${number}]` | LookupInMacroShape
-    >();
-  });
-});

packages/cbjs/src/clusterTypes/clusterTypes.ts

@@ -26,7 +26,6 @@ import {
   DocDef,
   DocDefKeyBodyShape,
   DocDefMatchingKey,
-  FriendlyPathToArrayIndex,
   GetKeyspaceOptions,
   IsNever,
   JsonDocumentDef,
@@ -44,23 +43,6 @@ import type { Scope } from '../scope.js';
 
 export type { DocDef };
 
-/**
- * Add friendly paths that are autocomplete friendly, is configured that way.
- * TODO incorporate this into the DocumentCodeCompletion
- */
-// prettier-ignore
-export type PathAutocomplete<Instance, Path> =
-  Instance extends Collection<infer T extends CouchbaseClusterTypes, infer B, infer S, infer C> ?
-    GetKeyspaceOptions<T, B, S, C> extends infer Options extends ClusterTypesOptions ?
-      Options extends { autocomplete?: infer Autocomplete } ?
-        Autocomplete extends 'friendly' ?
-          FriendlyPathToArrayIndex<Path> :
-        Path :
-      Path :
-    never :
-  never
-;
-
 // prettier-ignore
 export type CollectionDocDef<Instance> =
   Instance extends Collection<infer T, infer B, infer S, infer C> ?
@@ -143,6 +125,13 @@ export type ClusterTypesWith<
   };
 };
 
+// prettier-ignore
+export type CollectionOptions<Instance> =
+  Instance extends Collection<infer T, infer B, infer S, infer C> ?
+    GetKeyspaceOptions<T, B, S, C> :
+  never
+;
+
 export type AnyBucket = Bucket<any, any>;
 export type AnyScope = Scope<any, any, any>;
 export type AnyCollection = Collection<any, any, any, any>;

packages/cbjs/src/clusterTypes/kv/crud.spec-d.ts

@@ -15,8 +15,6 @@
  */
 import { describe, expectTypeOf, it } from 'vitest';
 
-import { FriendlyPathToArrayIndex } from '@cbjsdev/shared';
-
 import { connect } from '../../couchbase.js';
 import {
   GetReplicaResult,
@@ -27,7 +25,7 @@ import {
 import { PrefixScan, SamplingScan } from '../../rangeScan.js';
 import { LookupInSpec } from '../../sdspecs.js';
 import { StreamableReplicasPromise } from '../../streamablepromises.js';
-import { DocDef, PathAutocomplete } from '../clusterTypes.js';
+import { DocDef } from '../clusterTypes.js';
 
 type Book = { title: string };
 type QuarterSales = { sales: number[] };

packages/cbjs/src/clusterTypes/kv/lookup/lookupIn.types.spec-d.ts

@@ -27,6 +27,7 @@ import {
   LookupInResultEntry,
 } from '../../../index.js';
 import { LookupInSpec } from '../../../sdspecs.js';
+import { CollectionOptions } from '../../clusterTypes.js';
 import {
   LookupInInternalPath,
   LookupInResultEntries,
@@ -35,13 +36,16 @@ import {
   LookupInSpecResults,
 } from './lookupIn.types.js';
 
+type NoOptions = NonNullable<unknown>;
+
 describe('LookupInSpecs', () => {
   type TestDoc = {
     title: string;
     metadata: {
       tags: string[];
     };
     authors: [string, ...string[]];
+    editions: Record<`edition::${string}`, { publishedAt: number }>;
   };
 
   type TestDoc2 = {
@@ -258,11 +262,26 @@ describe('LookupInSpecs', () => {
         ]);
       });
 
-      it('should offer friendly autocomplete values for array indexes', async () => {
+      it('should offer friendly code completion path for array indexes', async () => {
+        const cluster = await connect<UserClusterTypes>('couchbase://127.0.0.1');
+        const collection = cluster.bucket('test').defaultCollection();
+
+        const result = await collection
+          .lookupIn('test__document')
+          .get('metadata.sales[]');
+
+        expectTypeOf(result).toEqualTypeOf<LookupInResult<[never]>>();
+      });
+
+      it('should offer friendly code completion path for record keys', async () => {
         const cluster = await connect<UserClusterTypes>('couchbase://127.0.0.1');
         const collection = cluster.bucket('test').defaultCollection();
 
-        const result = await collection.lookupIn('test__document').get('');
+        const result = await collection
+          .lookupIn('test__document')
+          .get('editions.#.publishedAt');
+
+        expectTypeOf(result).toEqualTypeOf<LookupInResult<[never]>>();
       });
 
       it('should infer the result type of an array of typeless specs based on collection documents', async () => {
@@ -307,9 +326,9 @@ describe('LookupInSpecs', () => {
 
   describe('LookupInSpecResult', () => {
     type Test<
-      Path extends LookupInInternalPath<TestDocDef, Opcode>,
+      Path extends LookupInInternalPath<NoOptions, TestDocDef, Opcode>,
       Opcode extends LookupInSpecOpCode,
-    > = LookupInSpecResult<LookupInSpec<TestDocDef, Opcode, Path>, TestDocDef>;
+    > = LookupInSpecResult<NoOptions, LookupInSpec<TestDocDef, Opcode, Path>, TestDocDef>;
 
     it('should infer the correct type', () => {
       expectTypeOf<
@@ -342,6 +361,7 @@ describe('LookupInSpecs', () => {
   describe('LookupInSpecResults', () => {
     it('should infer the correct result when using user defined document', () => {
       type Test = LookupInSpecResults<
+        NoOptions,
         [
           LookupInSpec<TestDocDef, CppProtocolSubdocOpcode.get, 'title'>,
           LookupInSpec<TestDocDef, CppProtocolSubdocOpcode.exists, 'title'>,
@@ -358,6 +378,7 @@ describe('LookupInSpecs', () => {
       // prettier-ignore
       expectTypeOf<
         LookupInSpecResults<
+          NoOptions,
           [
             LookupInSpec<AnyDocDef, CppProtocolSubdocOpcode.get, 'title'>,
             LookupInSpec<AnyDocDef, CppProtocolSubdocOpcode.exists, 'title'>,
@@ -372,6 +393,7 @@ describe('LookupInSpecs', () => {
       // prettier-ignore
       expectTypeOf<
         LookupInSpecResults<
+          NoOptions,
           [
             LookupInSpec<DocDef, CppProtocolSubdocOpcode.get, 'title'>,
             LookupInSpec<DocDef, CppProtocolSubdocOpcode.exists, 'title'>,