@syncular/core 0.15.32 → 0.15.34

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from './frames.js';
 export * from './message.js';
 export * from './realtime.js';
 export * from './rejection-details.js';
+export * from './relational-identifier.js';
 export * from './render.js';
 export * from './row-codec.js';
 export * from './segment.js';

package/dist/index.js

@@ -16,6 +16,7 @@ export * from './frames.js';
 export * from './message.js';
 export * from './realtime.js';
 export * from './rejection-details.js';
+export * from './relational-identifier.js';
 export * from './render.js';
 export * from './row-codec.js';
 export * from './segment.js';

package/dist/relational-identifier.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Portable relational identifier rules shared by typegen and every server
+ * runtime. PostgreSQL truncates identifiers after 63 UTF-8 bytes, while the
+ * relational Syncular projection reserves its own table/column namespace.
+ *
+ * Keeping this validation in core prevents a generated schema from passing
+ * typegen and then failing later when a server or testkit compiles it.
+ */
+export declare const PORTABLE_RELATIONAL_IDENTIFIER_MAX_BYTES = 63;
+export type PortableRelationalIdentifierFailure = 'empty' | 'reserved-prefix' | 'too-long';
+export declare class PortableRelationalIdentifierError extends Error {
+    readonly kind: string;
+    readonly identifier: string;
+    readonly failure: PortableRelationalIdentifierFailure;
+    readonly byteLength: number;
+    readonly code = "schema.invalid_identifier";
+    constructor(kind: string, identifier: string, failure: PortableRelationalIdentifierFailure, byteLength: number);
+}
+/** Validate one identifier against the strictest supported relational host. */
+export declare function validatePortableRelationalIdentifier(kind: string, identifier: string): void;

package/dist/relational-identifier.js

@@ -0,0 +1,44 @@
+/**
+ * Portable relational identifier rules shared by typegen and every server
+ * runtime. PostgreSQL truncates identifiers after 63 UTF-8 bytes, while the
+ * relational Syncular projection reserves its own table/column namespace.
+ *
+ * Keeping this validation in core prevents a generated schema from passing
+ * typegen and then failing later when a server or testkit compiles it.
+ */
+export const PORTABLE_RELATIONAL_IDENTIFIER_MAX_BYTES = 63;
+export class PortableRelationalIdentifierError extends Error {
+    kind;
+    identifier;
+    failure;
+    byteLength;
+    code = 'schema.invalid_identifier';
+    constructor(kind, identifier, failure, byteLength) {
+        const quoted = JSON.stringify(identifier);
+        const message = failure === 'empty'
+            ? `${kind} name must not be empty`
+            : failure === 'reserved-prefix'
+                ? `${kind} name ${quoted} uses a reserved prefix (sync_/_sync are the server storage namespace)`
+                : `${kind} name ${quoted} exceeds ${PORTABLE_RELATIONAL_IDENTIFIER_MAX_BYTES} bytes (Postgres identifier limit; actual UTF-8 length: ${byteLength} bytes)`;
+        super(message);
+        this.kind = kind;
+        this.identifier = identifier;
+        this.failure = failure;
+        this.byteLength = byteLength;
+        this.name = 'PortableRelationalIdentifierError';
+    }
+}
+/** Validate one identifier against the strictest supported relational host. */
+export function validatePortableRelationalIdentifier(kind, identifier) {
+    const byteLength = new TextEncoder().encode(identifier).length;
+    if (identifier.length === 0) {
+        throw new PortableRelationalIdentifierError(kind, identifier, 'empty', byteLength);
+    }
+    const lower = identifier.toLowerCase();
+    if (lower.startsWith('sync_') || lower.startsWith('_sync')) {
+        throw new PortableRelationalIdentifierError(kind, identifier, 'reserved-prefix', byteLength);
+    }
+    if (byteLength > PORTABLE_RELATIONAL_IDENTIFIER_MAX_BYTES) {
+        throw new PortableRelationalIdentifierError(kind, identifier, 'too-long', byteLength);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.15.32",
+  "version": "0.15.34",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './frames';
 export * from './message';
 export * from './realtime';
 export * from './rejection-details';
+export * from './relational-identifier';
 export * from './render';
 export * from './row-codec';
 export * from './segment';

package/src/relational-identifier.ts

@@ -0,0 +1,69 @@
+/**
+ * Portable relational identifier rules shared by typegen and every server
+ * runtime. PostgreSQL truncates identifiers after 63 UTF-8 bytes, while the
+ * relational Syncular projection reserves its own table/column namespace.
+ *
+ * Keeping this validation in core prevents a generated schema from passing
+ * typegen and then failing later when a server or testkit compiles it.
+ */
+
+export const PORTABLE_RELATIONAL_IDENTIFIER_MAX_BYTES = 63;
+
+export type PortableRelationalIdentifierFailure =
+  | 'empty'
+  | 'reserved-prefix'
+  | 'too-long';
+
+export class PortableRelationalIdentifierError extends Error {
+  readonly code = 'schema.invalid_identifier';
+
+  constructor(
+    readonly kind: string,
+    readonly identifier: string,
+    readonly failure: PortableRelationalIdentifierFailure,
+    readonly byteLength: number,
+  ) {
+    const quoted = JSON.stringify(identifier);
+    const message =
+      failure === 'empty'
+        ? `${kind} name must not be empty`
+        : failure === 'reserved-prefix'
+          ? `${kind} name ${quoted} uses a reserved prefix (sync_/_sync are the server storage namespace)`
+          : `${kind} name ${quoted} exceeds ${PORTABLE_RELATIONAL_IDENTIFIER_MAX_BYTES} bytes (Postgres identifier limit; actual UTF-8 length: ${byteLength} bytes)`;
+    super(message);
+    this.name = 'PortableRelationalIdentifierError';
+  }
+}
+
+/** Validate one identifier against the strictest supported relational host. */
+export function validatePortableRelationalIdentifier(
+  kind: string,
+  identifier: string,
+): void {
+  const byteLength = new TextEncoder().encode(identifier).length;
+  if (identifier.length === 0) {
+    throw new PortableRelationalIdentifierError(
+      kind,
+      identifier,
+      'empty',
+      byteLength,
+    );
+  }
+  const lower = identifier.toLowerCase();
+  if (lower.startsWith('sync_') || lower.startsWith('_sync')) {
+    throw new PortableRelationalIdentifierError(
+      kind,
+      identifier,
+      'reserved-prefix',
+      byteLength,
+    );
+  }
+  if (byteLength > PORTABLE_RELATIONAL_IDENTIFIER_MAX_BYTES) {
+    throw new PortableRelationalIdentifierError(
+      kind,
+      identifier,
+      'too-long',
+      byteLength,
+    );
+  }
+}