wirejs-resources 0.1.35-table-resource → 0.1.37-table-resource

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { withContext, requiresContext, Context, ContextWrapped } from './adapter
 export { Resource } from './resource.js';
 export { overrides } from './overrides.js';
 export { Secret } from './resources/secret.js';
-export { AnyKeyFieldOption, DistributedTable, DistributedTableOptions, Filter, FieldComparison, FieldComparisonOptions, FieldType, KeyFieldDefinition, KeyFieldOptions, Parser, PassThruParser, PKFieldTypes, RecordType, RecordKey, matchesFilter, } from './resources/distributed-table.js';
-export * from './types.js';
+export { DistributedTable, PassThruParser, matchesFilter, indexName } from './resources/distributed-table.js';
+export type * from './resources/distributed-table.js';
+export * from './types/index.js';
 export * from './derived-types.js';

package/dist/index.js

@@ -6,6 +6,6 @@ export { withContext, requiresContext, Context } from './adapters/context.js';
 export { Resource } from './resource.js';
 export { overrides } from './overrides.js';
 export { Secret } from './resources/secret.js';
-export { DistributedTable, PassThruParser, matchesFilter, } from './resources/distributed-table.js';
-export * from './types.js';
+export { DistributedTable, PassThruParser, matchesFilter, indexName } from './resources/distributed-table.js';
+export * from './types/index.js';
 export * from './derived-types.js';

package/dist/resources/distributed-table.d.ts

@@ -1,62 +1,6 @@
 import { Resource } from '../resource.js';
-export type KindaPretty<T> = T extends object ? {
-    [K in keyof T]: KindaPretty<T[K]>;
-} : T;
-export type PKFieldTypes = 'string' | 'number';
-export type DistributedTableOptions<T> = {
-    parse: Parser<T>;
-    key: {
-        partition: AnyKeyFieldOption<T>;
-        sort?: AnyKeyFieldOption<T>;
-    };
-};
-export type KeyFieldOptions<T> = {
-    [K in keyof T as K extends string ? K : never]: K extends string ? KeyFieldDefinition<T, K, T[K]> : never;
-};
-export type AnyKeyFieldOption<T> = KeyFieldOptions<T>[keyof KeyFieldOptions<T>];
-export type KeyFieldDefinition<T, FieldName extends string & keyof T, FieldType> = FieldType extends number ? {
-    field: FieldName & keyof T;
-    type: 'number';
-} : {
-    field: FieldName & keyof T;
-    type: 'string';
-};
-export type Parser<T> = (record: Record<string, any>) => T;
-export type RecordType<T extends DistributedTableOptions<any>> = T extends DistributedTableOptions<infer IT> ? IT : Record<string, any>;
-export type RecordKey<T, PK extends AnyKeyFieldOption<T>, SK extends AnyKeyFieldOption<T> | undefined> = Pick<T, PK['field'] | (SK extends Record<string, any> ? (SK extends undefined ? never : SK['field']) : never)>;
-export type FieldType<T> = undefined extends T ? (T | null) : T;
-export type FieldComparisonOptions<T> = {
-    [K in keyof T & string]?: {
-        eq: FieldType<T[K]>;
-    } | {
-        ne: FieldType<T[K]>;
-    } | {
-        gt: FieldType<T[K]>;
-    } | {
-        ge: FieldType<T[K]>;
-    } | {
-        lt: FieldType<T[K]>;
-    } | {
-        le: FieldType<T[K]>;
-    } | {
-        between: [FieldType<T[K]>, FieldType<T[K]>];
-    } | {
-        beginsWith: FieldType<T[K]>;
-    };
-};
-export type FieldComparison<T> = {
-    [K in keyof FieldComparisonOptions<T>]: Record<K, FieldComparisonOptions<T>[K]> & NoneOf<Exclude<keyof FieldComparisonOptions<T>, K>>;
-}[keyof FieldComparisonOptions<T>];
-export type NoneOf<Fields> = {
-    [K in Fields & string]?: never;
-};
-export type Filter<T> = (FieldComparison<T> & NoneOf<'and' | 'or' | 'not'>) | ({
-    and: (Filter<T>)[];
-} & NoneOf<keyof T | 'or' | 'not'>) | ({
-    or: (Filter<T>)[];
-} & NoneOf<keyof T | 'and' | 'not'>) | ({
-    not: Filter<T>;
-} & NoneOf<keyof T | 'and' | 'or'>);
+import { AllIndexesByName, AnyDistributedTable, Filter, Index, IndexFieldNames, IndexName, KeyCondition, KindaPretty, Parser, RecordKey } from '../types/resources/distributed-table.js';
+export declare function indexName<Idx extends Index<any>>(index: Idx): IndexName<Idx>;
 export declare function matchesFilter<T>(record: T, filter: Filter<T>): boolean;
 export declare function PassThruParser<T>(record: Record<string, any>): T;
 /**
@@ -70,29 +14,48 @@ export declare function PassThruParser<T>(record: Record<string, any>): T;
  *
  * High cardinality, non-sequential partition keys allow for the best overall scaling.
  */
-export declare class DistributedTable<const P extends Parser<any>, const T extends KindaPretty<ReturnType<P>>, const PK extends AnyKeyFieldOption<T>, const SK extends AnyKeyFieldOption<T> | undefined> extends Resource {
+export declare class DistributedTable<const P extends Parser<any>, const T extends KindaPretty<ReturnType<P>>, const Key extends Index<T>, const Indexes extends Index<T>[] | undefined = undefined> extends Resource implements AnyDistributedTable {
     #private;
     parse: P;
-    partitionKey: PK;
-    sort: SK | undefined;
+    key: Key;
+    indexes: Indexes | undefined;
     constructor(scope: Resource | string, id: string, options: {
         parse: P;
-        key: {
-            partition: PK;
-            sort?: SK;
-        };
+        key: Key;
+        indexes?: Indexes;
     });
-    get partitionKeyName(): PK['field'];
-    get sortKeyName(): 'field' extends keyof SK ? SK['field'] : undefined;
+    get partitionKeyName(): Key['partition']['field'];
+    get sortKeyName(): 'field' extends keyof Key['sort'] ? (Key['sort']['field'] extends string ? Key['sort']['field'] : undefined) : undefined;
     save(item: T): Promise<void>;
     saveMany(items: T[]): Promise<void>;
-    delete(item: KindaPretty<RecordKey<T, PK, SK>>): Promise<void>;
-    deleteMany(items: (KindaPretty<RecordKey<T, PK, SK>>)[]): Promise<void>;
-    get(key: KindaPretty<RecordKey<T, PK, SK>>): Promise<KindaPretty<T> | undefined>;
+    delete(item: KindaPretty<RecordKey<T, Key>>): Promise<void>;
+    deleteMany(items: (KindaPretty<RecordKey<T, Key>>)[]): Promise<void>;
+    get(key: KindaPretty<RecordKey<T, Key>>): Promise<KindaPretty<T> | undefined>;
+    /**
+     * Performs a scan of the entire table.
+     *
+     * This is not recommended for large tables. It may be slow and expensive.
+     *
+     * Favor queries against the primary key and indexes instead.
+     *
+     * @param options
+     */
     scan(options: {
         filter?: Filter<T>;
     }): AsyncGenerator<T>;
-    query(partition: KindaPretty<Pick<T, PK['field']>>, options?: {
-        filter?: Filter<T>;
+    /**
+     * Performs a query of the table within a partition of either the primary key or
+     * an index.
+     *
+     * In local development environments, this is currently implemented as a full table
+     * scan. In production environments, this will generally implemented as a query against
+     * an index followed by a filtering step.
+     *
+     * @param options
+     */
+    query<const GivenPartition extends keyof AllIndexesByName<DistributedTable<P, T, Key, Indexes>> & string>(options: {
+        by: GivenPartition;
+        where: KeyCondition<DistributedTable<P, T, Key, Indexes>, GivenPartition>;
+        filter?: Filter<Omit<T, IndexFieldNames<DistributedTable<P, T, Key, Indexes>, GivenPartition> & string>>;
     }): AsyncGenerator<T>;
 }

package/dist/resources/distributed-table.js

@@ -1,6 +1,9 @@
 import { Resource } from '../resource.js';
 import { FileService } from '../services/file.js';
 import { overrides } from '../overrides.js';
+export function indexName(index) {
+    return `${index.partition.field}${index.sort ? `-${index.sort.field}` : ''}`;
+}
 export function matchesFilter(record, filter) {
     if (filter.and) {
         return filter.and.every(sub => matchesFilter(record, sub));
@@ -54,23 +57,21 @@ export function PassThruParser(record) {
  */
 export class DistributedTable extends Resource {
     parse;
-    partitionKey;
-    sort;
+    key;
+    indexes;
     #fileService;
     constructor(scope, id, options) {
         super(scope, id);
         this.parse = options.parse;
-        this.partitionKey = options.key.partition;
-        this.sort = options.key.sort;
+        this.key = options.key;
+        this.indexes = options.indexes;
         this.#fileService = new (overrides.FileService || FileService)(this, 'files');
     }
     get partitionKeyName() {
-        const [pkField] = Object.keys(this.partitionKey);
-        return pkField;
+        return this.key.partition.field;
     }
     get sortKeyName() {
-        const [skField] = Object.keys(this.sort ?? {});
-        return skField;
+        return this.key.sort?.field;
     }
     #getFilename(key) {
         const parts = [key[this.partitionKeyName]];
@@ -113,6 +114,15 @@ export class DistributedTable extends Resource {
             throw err;
         }
     }
+    /**
+     * Performs a scan of the entire table.
+     *
+     * This is not recommended for large tables. It may be slow and expensive.
+     *
+     * Favor queries against the primary key and indexes instead.
+     *
+     * @param options
+     */
     async *scan(options) {
         for await (const filename of this.#fileService.list()) {
             const data = await this.#fileService.read(filename);
@@ -122,16 +132,30 @@ export class DistributedTable extends Resource {
             }
         }
     }
-    async *query(partition, options = {}) {
-        const prefix = partition[this.partitionKeyName];
-        for await (const filename of this.#fileService.list({ prefix })) {
-            const data = await this.#fileService.read(filename);
-            const record = this.parse(JSON.parse(data));
-            if (record[this.partitionKeyName] === partition[this.partitionKeyName]
-                && (!options.filter || matchesFilter(record, options.filter))) {
-                yield record;
+    /**
+     * Performs a query of the table within a partition of either the primary key or
+     * an index.
+     *
+     * In local development environments, this is currently implemented as a full table
+     * scan. In production environments, this will generally implemented as a query against
+     * an index followed by a filtering step.
+     *
+     * @param options
+     */
+    async *query(options) {
+        // decompose for injection into `and` clause, wherein each k-v condition
+        // is expected to be independent.
+        const decomposedWhere = Object.entries(options.where).map(([k, v]) => ({
+            [k]: v
+        }));
+        yield* this.scan({
+            filter: {
+                and: [
+                    ...decomposedWhere,
+                    ...(options.filter ? [options.filter] : [])
+                ]
             }
-        }
+        });
     }
 }
 // export type Todo = {
@@ -142,7 +166,40 @@ export class DistributedTable extends Resource {
 // const userTodos = new DistributedTable('app', 'userTodos', {
 // 	parse: PassThruParser<Todo & { userId: string }>,
 // 	key: {
-// 		partition: { userId: 'string' },
-// 		sort: { id: 'string' }
-// 	}
+// 		partition: { field: 'userId', type: 'string' },
+// 		sort: { field: 'order', type: 'number' }
+// 		// sort: { field: 'id', type: 'string' }
+// 		// sort: { }
+// 	},
+// 	indexes: [
+// 		{
+// 			partition: { field: 'text', type: 'string' },
+// 			sort: { field: 'userId', type: 'string' }
+// 			// sort: { field: 'order', type: 'number' }
+// 		}
+// 	]
 // });
+// type I = typeof userTodos['key'];
+// type T1 = typeof userTodos['key']['partition']['field'];
+// type T2 = typeof userTodos['key']['sort']['field'];
+// type T3 = typeof userTodos['indexes'];
+// type TTT1 = AllIndexes<typeof userTodos>;
+// type TTT2 = AllIndexesByName<typeof userTodos>;
+// type AnyIndex = Index<any>;
+// type TEST1 = I extends Index<any> ? 'yes' : 'no';
+// userTodos.query({
+// 	by: 'userId-order',
+// 	where: {
+// 		// maybe the key here can be the actual name of the field.
+// 		// maybe even follow the filter pattern, but only expose the `eq` operation:
+// 		// { [field]: { eq: T } }
+// 		userId: { eq: 'something' },
+// 		// id: {
+// 		// 	eq: 'something'
+// 		// }
+// 		// same here. name of the actual sort key field.
+// 		// id: {
+// 		// 	beginsWith: 'something'
+// 		// },
+// 	},
+// })

package/dist/services/authentication.d.ts

@@ -1,7 +1,7 @@
 import { Resource } from '../resource.js';
 import { ContextWrapped } from '../adapters/context.js';
 import type { CookieJar } from '../adapters/cookie-jar.js';
-import type { User, AuthenticationError, AuthenticationMachineInput, AuthenticationMachineState, AuthenticationServiceOptions } from '../types.js';
+import type { User, AuthenticationError, AuthenticationMachineInput, AuthenticationMachineState, AuthenticationServiceOptions } from '../types/index.js';
 export declare class AuthenticationService extends Resource {
     #private;
     constructor(scope: Resource | string, id: string, { duration, keepalive, cookie }?: AuthenticationServiceOptions);

package/dist/types/index.d.ts

@@ -0,0 +1,74 @@
+export * from './resources/distributed-table.js';
+export type User = {
+    /**
+     * Something that uniquely identifies the user in the authentication system
+     * and does not change over time.
+     */
+    id: string;
+    /**
+     * The self-identifier the user has chosen to log in with.
+     */
+    username: string;
+    /**
+     * The name this user will be known by to other users.
+     */
+    displayName: string;
+};
+export type AuthenticationField = {
+    label: string;
+    type: 'text' | 'password';
+    isRequired?: boolean;
+};
+export type AuthenticationAction = {
+    name: string;
+    title?: string;
+    description?: string;
+    message?: string;
+    fields?: Record<string, AuthenticationField>;
+    buttons?: readonly string[];
+};
+export type AuthenticationState = {
+    state: 'authenticated';
+    user: User;
+} | {
+    state: 'unauthenticated';
+    user: undefined;
+};
+export type AuthenticationMachineAction = Readonly<AuthenticationAction & {
+    key: string;
+}>;
+export type AuthenticationMachineState = AuthenticationState & {
+    message?: string;
+    actions: Record<string, AuthenticationMachineAction>;
+};
+export type AuthenticationMachineInput = {
+    key: string;
+    inputs?: Record<string, string | number | boolean>;
+    verb?: string;
+};
+export type AuthenticationMachineInputFor<T extends AuthenticationMachineAction> = {
+    key: T['key'];
+    verb: string;
+    inputs: T['fields'] extends undefined ? Record<string, never> : {
+        [K in keyof T['fields']]: FieldInputFor<T['fields'][K]>;
+    };
+};
+export type FieldInputFor<T> = T extends AuthenticationField ? T['type'] extends ('text' | 'password') ? string : never : never;
+export type AuthenticationError = {
+    message: string;
+    field?: string;
+};
+export type AuthenticationServiceOptions = {
+    /**
+     * The number of seconds the authentication session stays alive.
+     */
+    duration?: number;
+    /**
+     * Whether to automatically extend (keep alive) an authentication session when used.
+     */
+    keepalive?: boolean;
+    /**
+     * The name of the cookie to use to store the authentication state JWT.
+     */
+    cookie?: string;
+};

package/dist/types/index.js

@@ -0,0 +1 @@
+export * from './resources/distributed-table.js';

package/dist/types/resources/distributed-table.d.ts

@@ -0,0 +1,116 @@
+import type { Resource } from '../../resource.js';
+export type KindaPretty<T> = T extends object ? {
+    [K in keyof T]: KindaPretty<T[K]>;
+} : T;
+export type PKFieldTypes = 'string' | 'number';
+export type StringToType<S extends 'string' | 'number'> = S extends 'string' ? string : S extends 'number' ? number : never;
+export type IDistributedTableOptions<T> = {
+    parse: Parser<T>;
+    key: {
+        partition: AnyKeyFieldOption<T>;
+        sort?: AnyKeyFieldOption<T>;
+    };
+};
+export type KeyFieldOptions<T> = {
+    [K in keyof T as K extends string ? K : never]: K extends string ? KeyFieldDefinition<T, K, T[K]> : never;
+};
+export type AnyKeyFieldOption<T> = KeyFieldOptions<T>[keyof KeyFieldOptions<T>];
+export type KeyFieldDefinition<T = Record<string, any>, FieldName extends string & keyof T = string & keyof T, FieldType = T[FieldName]> = FieldType extends number ? {
+    readonly field: FieldName & keyof T;
+    readonly type: 'number';
+} : {
+    readonly field: FieldName & keyof T;
+    readonly type: 'string';
+};
+export type Index<T> = {
+    readonly partition: AnyKeyFieldOption<T>;
+    readonly sort?: AnyKeyFieldOption<T>;
+};
+export type Parser<T> = (record: Record<string, any>) => T;
+export type RecordType<T extends IDistributedTableOptions<any>> = T extends IDistributedTableOptions<infer IT> ? IT : Record<string, any>;
+export type RecordKey<T, Idx extends Index<T>> = Pick<T, Idx['partition']['field'] | ('field' extends keyof Idx['sort'] ? (Idx['sort']['field'] extends keyof T ? Idx['sort']['field'] : never) : never)>;
+export type FieldType<T> = undefined extends T ? (T | null) : T;
+export type FieldComparisonOptions<T> = {
+    [K in keyof T & string]?: {
+        eq: FieldType<T[K]>;
+    } | {
+        ne: FieldType<T[K]>;
+    } | {
+        gt: FieldType<T[K]>;
+    } | {
+        ge: FieldType<T[K]>;
+    } | {
+        lt: FieldType<T[K]>;
+    } | {
+        le: FieldType<T[K]>;
+    } | {
+        between: [FieldType<T[K]>, FieldType<T[K]>];
+    } | {
+        beginsWith: FieldType<T[K]>;
+    };
+};
+export type FieldComparison<T> = {
+    [K in keyof FieldComparisonOptions<T>]: Record<K, FieldComparisonOptions<T>[K]> & NoneOf<Exclude<keyof FieldComparisonOptions<T>, K>>;
+}[keyof FieldComparisonOptions<T>];
+export type NoneOf<Fields> = {
+    [K in Fields & string]?: never;
+};
+export type Filter<T> = (FieldComparison<T> & NoneOf<'and' | 'or' | 'not'>) | ({
+    and: (Filter<T>)[];
+} & NoneOf<keyof T | 'or' | 'not'>) | ({
+    or: (Filter<T>)[];
+} & NoneOf<keyof T | 'and' | 'not'>) | ({
+    not: Filter<T>;
+} & NoneOf<keyof T | 'and' | 'or'>);
+export type IndexName<I extends Index<any>> = I extends {
+    readonly partition: infer P extends {
+        readonly field: string;
+    };
+    readonly sort?: infer S;
+} ? `${P['field']}${S extends {
+    readonly field: string;
+} ? `-${S['field']}` : ''}` : never;
+export type IndexNames<Indexes> = (keyof IndexesByName<Indexes>) & string;
+export type IndexesByName<Indexes> = KindaPretty<Indexes extends [infer I extends Index<any>, ...infer Rest] ? Record<IndexName<I>, I> & IndexesByName<Rest> : unknown>;
+export type AllIndexes<T extends AnyDistributedTable> = T extends AnyDistributedTable ? [
+    T['key'],
+    ...(Exclude<T['indexes'], undefined> extends never ? [] : Exclude<T['indexes'], undefined>)
+] : never;
+export type AllIndexesByName<T extends AnyDistributedTable> = IndexesByName<AllIndexes<T>>;
+export type KeyCondition<T extends AnyDistributedTable, Index extends keyof AllIndexesByName<T>> = {
+    [K in PartitionKeyName<T, Index> & string]: {
+        eq: PartitionKeyType<T, Index>;
+    };
+} & {
+    [K in MatchingSortKeyName<T, Index>]+?: SortKeyCondition<T, Index>;
+};
+export type PartitionKeyType<T extends AnyDistributedTable, Idx extends keyof AllIndexesByName<T>> = AllIndexesByName<T>[Idx] extends Index<any> ? StringToType<AllIndexesByName<T>[Idx]['partition']['type']> : never;
+export type PartitionKeyName<T extends AnyDistributedTable, Idx extends keyof AllIndexesByName<T>> = AllIndexesByName<T>[Idx] extends Index<any> ? AllIndexesByName<T>[Idx]['partition']['field'] : never;
+export type MatchingSortKeyDefinition<T extends AnyDistributedTable, Idx extends keyof AllIndexesByName<T>> = AllIndexesByName<T>[Idx] extends Index<any> ? AllIndexesByName<T>[Idx]['sort'] : never;
+export type MatchingSortKeyType<T extends AnyDistributedTable, Idx extends keyof AllIndexesByName<T>> = MatchingSortKeyDefinition<T, Idx> extends AnyKeyFieldOption<any> ? StringToType<MatchingSortKeyDefinition<T, Idx>['type']> : never;
+export type MatchingSortKeyName<T extends AnyDistributedTable, Idx extends keyof AllIndexesByName<T>> = MatchingSortKeyDefinition<T, Idx> extends AnyKeyFieldOption<any> ? MatchingSortKeyDefinition<T, Idx>['field'] : never;
+export type SortKeyCondition<T extends AnyDistributedTable, Idx extends keyof AllIndexesByName<T>> = MatchingSortKeyType<T, Idx> extends (string | number) ? ({
+    eq: MatchingSortKeyType<T, Idx>;
+} | {
+    ne: MatchingSortKeyType<T, Idx>;
+} | {
+    lt: MatchingSortKeyType<T, Idx>;
+} | {
+    le: MatchingSortKeyType<T, Idx>;
+} | {
+    gt: MatchingSortKeyType<T, Idx>;
+} | {
+    ge: MatchingSortKeyType<T, Idx>;
+} | {
+    between: MatchingSortKeyType<T, Idx>;
+} | {
+    beginsWith: MatchingSortKeyType<T, Idx>;
+}) : never;
+export type IndexFieldNames<T extends AnyDistributedTable, Idx extends keyof AllIndexesByName<T>> = PartitionKeyName<T, Idx> | MatchingSortKeyName<T, Idx>;
+export interface AnyDistributedTable extends Resource {
+    parse: Parser<any>;
+    key: Index<any>;
+    indexes: Index<any>[] | undefined;
+    get partitionKeyName(): string;
+    get sortKeyName(): string | undefined;
+}

package/dist/types/resources/distributed-table.js

@@ -0,0 +1,2 @@
+;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wirejs-resources",
-	"version": "0.1.35-table-resource",
+	"version": "0.1.37-table-resource",
 	"description": "Basic services and server-side resources for wirejs apps",
 	"type": "module",
 	"main": "./dist/index.js",