ser-des work (#92)

* unficiation of codec types

* snakeCaseInterop => keyTransformer

* some unit tests on ser-des options

Author: toptobes

etc/astra-db-ts.api.md

@@ -8,7 +8,7 @@ class Author {
   constructor(public fullName: string, public birthdate: Date) {}
 }
 
-export default async function CollClassMappingExample(name: string, db: Db) {
+export async function CollectionClassMappingExample(name: string, db: Db) {
   const coll = await db.createCollection<Book>(name, {
     serdes: {
       mutateInPlace: true,
@@ -26,13 +26,16 @@ export default async function CollClassMappingExample(name: string, db: Db) {
   console.log(inserted);
 
   // Find a document
-  const found = await coll.findOne({ _id: '123-4-567-89012-3' });
+  const found = await coll.findOne({ isbn: '123-4-567-89012-3' });
   console.dir(found, { depth: null });
 }
 
 const BookCodec = CollCodecs.forPath([], {
   serialize: (_, value: unknown, ctx) => {
     if (!(value instanceof Book)) {
+      if (value && typeof value === 'object' && 'isbn' in value) {
+        return ctx.recurse({ ...value, _id: value.isbn, isbn: undefined });
+      }
       return ctx.continue();
     }
 
@@ -46,15 +49,15 @@ const BookCodec = CollCodecs.forPath([], {
       },
     })
   },
+  deserializeGuard(_, ctx) {
+    return !ctx.parsingInsertedId;
+  },
   deserialize: (_, value: SomeDoc, ctx) => {
-    if (ctx.parsingInsertedId) {
-      return ctx.continue();
-    }
-
-    return ctx.done(new Book(
+    const book = new Book(
       value.title,
       new Author(`${value.author.lastName}, ${value.author.firstName}`, new Date(value.author.birthdate)),
       value._id,
-    ));
+    );
+    return ctx.done(book);
   },
 });

examples/serdes/src/collections/class-mapping.ts

@@ -1,5 +1,7 @@
 import { DataAPIClient } from '@datastax/astra-db-ts';
 import 'dotenv/config';
+import { TableCustomDatatypesExample } from '@/src/tables/custom-datatypes';
+import { CollectionClassMappingExample } from '@/src/collections/class-mapping';
 
 const client = new DataAPIClient(process.env.CLIENT_DB_TOKEN);
 const db = client.db(process.env.CLIENT_DB_URL!);
@@ -11,15 +13,14 @@ const cleanup = () => db.dropCollection(NAME);
 (async () => {
   await cleanup();
 
-  const files = [
-    './tables/custom-datatypes',
-    './collections/class-mapping',
+  const functions = [
+    TableCustomDatatypesExample,
+    CollectionClassMappingExample,
   ];
 
-  for (const file of files) {
+  for (const func of functions) {
     await using _ = { [Symbol.asyncDispose]: cleanup };
-    const example = await import(file);
-    console.log(`Running ${file}...`);
-    await example.default(NAME, db);
+    console.log(`Running ${func.name}...`);
+    await func(NAME, db);
   }
 })();

examples/serdes/src/index.ts

@@ -2,6 +2,7 @@ import {
   $DeserializeForTable,
   $SerializeForTable,
   Db,
+  Camel2SnakeCase,
   SomeDoc,
   TableCodec,
   TableCodecs,
@@ -16,7 +17,7 @@ interface User {
   milestones: AssocList<string, Date>,
 }
 
-export default async function TableCustomDatatypesExample(name: string, db: Db) {
+export async function TableCustomDatatypesExample(name: string, db: Db) {
   const table = await db.createTable<User>(name, {
     definition: {
       columns: {
@@ -28,8 +29,8 @@ export default async function TableCustomDatatypesExample(name: string, db: Db)
       primaryKey: 'user_id',
     },
     serdes: {
-      mutateInPlace: true,    // Optimization for serialization if you don't need to use the doc again once you pass it in
-      snakeCaseInterop: true, // Convert camelCase to/from snake_case for column names
+      mutateInPlace: true, // Optimization for serialization if you don't need to use the doc again once you pass it in
+      keyTransformer: new Camel2SnakeCase(), // Convert camelCase to/from snake_case for column names
       codecs: [
         DateCodec,
         UserIDCodec,
@@ -64,7 +65,7 @@ class UserID {
 
 const UserIDCodec = TableCodecs.forName('userId', {
   serialize: (_, value: UserID, ctx) =>  ctx.done(value.uuid),
-  deserialize: (value: string, ctx) => ctx.done(new UserID(value)),
+  deserialize: (_, value: string, ctx) => ctx.done(new UserID(value)),
 });
 
 // Demonstrates validation logic through codecs
@@ -76,15 +77,15 @@ const FullNameCodec = TableCodecs.forName('fullName', {
     }
     return ctx.done(value);
   },
-  deserialize: (value: string, ctx) => ctx.done(value),
+  deserialize: (_, value: string, ctx) => ctx.done(value),
 });
 
 // Example of retrofitting a type you don't own (or don't want to pollute with serdes logic)
 
 const DateCodec = TableCodecs.forType('timestamp', {
   serializeClass: Date,
   serialize: (_, value: Date, ctx) => ctx.done(value.toISOString()),
-  deserialize: (value: string, ctx) => ctx.done(new Date(value)),
+  deserialize: (_, value: string, ctx) => ctx.done(new Date(value)),
 });
 
 // Association list for demonstrating codec composition
@@ -96,12 +97,12 @@ class AssocList<K, V> implements TableCodec<typeof AssocList> {
     return ctx.recurse(Object.fromEntries(this.unwrap));
   }
 
-  public static [$DeserializeForTable](obj: Record<string, unknown>[], ctx: TableDesCtx, def: SomeDoc) {
+  public static [$DeserializeForTable](_: unknown, obj: Record<string, unknown>[], ctx: TableDesCtx, def: SomeDoc) {
     const values = Object.entries(obj);
 
     for (let i = 0; i < values.length; i++) {
-      values[i][0] = ctx.codecs.type[def.keyType]?.deserialize(values[i][0], ctx, def)[1] ?? values[i][0];
-      values[i][1] = ctx.codecs.type[def.valueType]?.deserialize(values[i][1], ctx, def)[1] ?? values[i][1];
+      values[i][0] = ctx.codecs.type[def.keyType]?.deserialize(undefined, values[i][0], ctx, def)[1] ?? values[i][0];
+      values[i][1] = ctx.codecs.type[def.valueType]?.deserialize(undefined, values[i][1], ctx, def)[1] ?? values[i][1];
     }
 
     return ctx.done(new AssocList(values));

examples/serdes/src/tables/custom-datatypes.ts

@@ -22,11 +22,22 @@ local)
   npm run build
   npm pack
 
+  dirs="$2"
+
+  if [ -z "$dirs" ]; then
+    dirs="examples/*"
+  fi
+
   # Does said installation
-  for dir in examples/*; do
+  for dir in $dirs; do
+    if [ ! -d "$dir" ]; then
+      echo "Directory $dir does not exist"
+      continue
+    fi
     cd "$cwd/$dir" || exit 1
     npm i "${tarball_dir}"/datastax-astra-db-ts-*.tgz
     npm i @datastax/astra-db-ts
+    cd "$cwd" || exit 1
   done
 
   # Cleanup (tarball no longer required)

scripts/update-example-client-dep.sh

@@ -17,9 +17,9 @@ import { UUID } from '@/src/documents/datatypes/uuid';
 import { ObjectId } from '@/src/documents/datatypes/object-id';
 import { DataAPIVector } from '@/src/documents/datatypes/vector';
 import { DataAPITimestamp } from '@/src/documents/datatypes/dates';
-import { CollDesCtx, CollSerCtx, TableSerCtx } from '@/src/documents';
-import { CodecHolder } from '@/src/lib/api/ser-des/codecs';
+import { CollDesCtx, CollSerCtx } from '@/src/documents';
 import { EmptyObj, SerDesFn } from '@/src/lib';
+import { CodecOpts, RawCodec } from '@/src/lib/api/ser-des/codecs';
 import { $DeserializeForCollection, $SerializeForCollection } from '@/src/documents/collections/ser-des/constants';
 
 /**
@@ -46,19 +46,7 @@ export type CollCodec<_Class extends CollCodecClass> = EmptyObj;
 /**
  * @public
  */
-export class CollCodecs implements CodecHolder<CollCodecSerDesFns> {
-  /**
-   * @internal
-   */
-  public readonly get: CodecHolder<CollCodecSerDesFns>['get'];
-
-  /**
-   * @internal
-   */
-  public constructor(state: typeof this.get) {
-    this.get = state;
-  }
-
+export class CollCodecs {
   public static Defaults = {
     $date: CollCodecs.forType('$date', {
       serializeClass: Date,
@@ -74,45 +62,32 @@ export class CollCodecs implements CodecHolder<CollCodecSerDesFns> {
     $objectId: CollCodecs.forType('$objectId', ObjectId),
   };
 
-  public static Overrides = {
-    USE_DATA_API_TIMESTAMPS_OVER_DATES: CollCodecs.forType('$date', DataAPITimestamp),
-    // USE_NUMBER_ARRAYS_FOR_VECTORS:
-  };
-
-  public static forPath(path: string[], clazz: CollCodecClass): CollCodecs
-
-  public static forPath(path: string[], opts: CollCodecSerDesFns): CollCodecs
+  public static USE_DATA_API_TIMESTAMPS_FOR_DATES = CollCodecs.forType('$date', DataAPITimestamp);
 
-  public static forPath(path: string[], clazzOrOpts: CollCodecClass | CollCodecSerDesFns): CollCodecs {
-    if ($DeserializeForCollection in clazzOrOpts) {
-      return new CollCodecs({ codecType: 'path', path, deserialize: clazzOrOpts[$DeserializeForCollection] });
-    }
-    return new CollCodecs({ codecType: 'path', path, ...clazzOrOpts });
+  public static forPath(path: string[], optsOrClass: CodecOpts<CollCodecSerDesFns, CollSerCtx, CollDesCtx> | CollCodecClass): RawCodec<CollCodecSerDesFns> {
+    return {
+      path,
+      ...($DeserializeForCollection in optsOrClass)
+        ? { deserialize: optsOrClass[$DeserializeForCollection] }
+        : optsOrClass,
+    };
   }
 
-  public static forName(name: string, clazz: CollCodecClass): CollCodecs
-
-  public static forName(name: string, opts: CollCodecSerDesFns): CollCodecs
-
-  public static forName(name: string, clazzOrOpts: CollCodecClass | CollCodecSerDesFns): CollCodecs {
-    if ($DeserializeForCollection in clazzOrOpts) {
-      return new CollCodecs({ codecType: 'name', name, deserialize: clazzOrOpts[$DeserializeForCollection] });
-    }
-    return new CollCodecs({ codecType: 'name', name, ...clazzOrOpts });
+  public static forName(name: string, optsOrClass: CodecOpts<CollCodecSerDesFns, CollSerCtx, CollDesCtx> | CollCodecClass): RawCodec<CollCodecSerDesFns> {
+    return {
+      name,
+      ...($DeserializeForCollection in optsOrClass)
+        ? { deserialize: optsOrClass[$DeserializeForCollection] }
+        : optsOrClass,
+    };
   }
 
-  public static forType(type: string, clazz: CollCodecClass): CollCodecs;
-
-  public static forType(type: string, opts: CollCodecSerDesFns & { serializeGuard: (value: unknown, ctx: TableSerCtx) => boolean }): CollCodecs;
-
-  public static forType(type: string, opts: CollCodecSerDesFns & { serializeClass: new (...args: any[]) => any }): CollCodecs;
-
-  public static forType(type: string, opts: CollCodecSerDesFns & { deserializeOnly: true }): CollCodecs;
-
-  public static forType(type: string, clazzOrOpts: CollCodecClass | CollCodecSerDesFns): CollCodecs {
-    if ($DeserializeForCollection in clazzOrOpts) {
-      return new CollCodecs({ codecType: 'type', type, deserialize: clazzOrOpts[$DeserializeForCollection] });
-    }
-    return new CollCodecs({ codecType: 'type', type, ...clazzOrOpts });
+  public static forType(type: string, optsOrClass: CodecOpts<CollCodecSerDesFns, CollSerCtx, CollDesCtx> | CollCodecClass): RawCodec<CollCodecSerDesFns> {
+    return {
+      type,
+      ...($DeserializeForCollection in optsOrClass)
+        ? { deserialize: optsOrClass[$DeserializeForCollection] }
+        : optsOrClass,
+    };
   }
 }

src/documents/collections/ser-des/codecs.ts

@@ -36,9 +36,8 @@ export interface CollDesCtx extends BaseDesCtx<CollCodecSerDesFns> {
 /**
  * @public
  */
-export interface CollectionSerDesConfig extends BaseSerDesConfig<CollCodecs, CollCodecSerDesFns, CollSerCtx, CollDesCtx> {
+export interface CollectionSerDesConfig extends BaseSerDesConfig<CollCodecSerDesFns, CollSerCtx, CollDesCtx> {
   enableBigNumbers?: boolean,
-  codecs?: CollCodecs[],
 }
 
 /**
@@ -94,6 +93,7 @@ const DefaultCollectionSerDesCfg = {
       }
     }
 
+
     if (typeof value === 'object' && value !== null) {
       if (value[$SerializeForCollection]) {
         if ((resp = value[$SerializeForCollection](ctx))[0] !== CONTINUE) {
@@ -143,7 +143,7 @@ const DefaultCollectionSerDesCfg = {
       }
     }
 
-    if (ctx.keys?.length === 1 && (ctx.keys[0] in codecs.type)) {
+    if (ctx.keys?.length === 1 && ctx.keys[0] in codecs.type) {
       if ((resp = codecs.type[ctx.keys[0]].deserialize?.(key, value, ctx) ?? ctx.continue())[0] !== CONTINUE) {
         return resp;
       }