nullable properties are missing in model

[thedomeffm]

Package version

21.6.1

Describe the bug

The nullable column "clientId" does not get initialized so the logical "null" check on the model is not executed as expected.

// The model
export default class CognitoUserPoolClient extends BaseModel {
    @column({ isPrimary: true })
    declare id: string;

    /* ... */

    @column()
    declare isDefault: boolean;

    @column()
    declare userPoolId: string;

    @column()
    declare clientName: string;

    @column()
    declare clientId: string | null; // <-----
}

// The code
const defaultCognitoUserPoolClient = await CognitoUserPoolClient.firstOrCreate(
    { isDefault: true },
    {
        userPoolId: 'foo',
        clientName: 'bar',
    },
);

console.log(defaultCognitoUserPoolClient); // log 1 <--
await defaultCognitoUserPoolClient.refresh();
console.log(defaultCognitoUserPoolClient); // log 2 <--

if (defaultCognitoUserPoolClient.clientId === null) {
    // consider null clientId as not created UserPoolClient.
    const userPoolClient = await cognitoIdentityProvider.createUserPoolClient(
        /* ... */
    );
    await defaultCognitoUserPoolClient.merge({ clientId: userPoolClient.ClientId }).save();
}

The Problem: the defaultCognitoUserPoolClient.clientId === null is always false when not calling await defaultCognitoUserPoolClient.refresh();! The clientId is just missing in the model.

see log 1 output (BEFORE refresh):

CognitoUserPoolClient {
  modelOptions: { connection: 'postgres' },
  modelTrx: undefined,
  transactionListener: [Function: bound listener],
  fillInvoked: false,
  cachedGetters: {},
  forceUpdate: false,
  '$columns': {},
  '$attributes': {
    isDefault: true,
    userPoolId: 'foo',
    clientName: 'bar',
    id: '019840bf-6aa3-75e6-bee8-7c931db59490',
    createdAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
    updatedAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US }
  },
  '$original': {
    isDefault: true,
    userPoolId: 'foo',
    clientName: 'bar',
    id: '019840bf-6aa3-75e6-bee8-7c931db59490',
    createdAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
    updatedAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US }
  },
  '$preloaded': {},
  '$extras': {},
  '$sideloaded': {},
  '$isPersisted': true,
  '$isDeleted': false,
  '$isLocal': true,
  isDefault: true,
  userPoolId: 'foo',
  clientName: 'bar',
  id: '019840bf-6aa3-75e6-bee8-7c931db59490',
  createdAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
  updatedAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US }
}

and log 2 output (AFTER refresh):

CognitoUserPoolClient {
  modelOptions: { connection: 'postgres' },
  modelTrx: undefined,
  transactionListener: [Function: bound listener],
  fillInvoked: true,
  cachedGetters: {},
  forceUpdate: false,
  '$columns': {},
  '$attributes': {
    id: '019840bf-6aa3-75e6-bee8-7c931db59490',
    createdAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
    updatedAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
    isDefault: true,
    userPoolId: 'foo',
    clientName: 'bar',
    clientId: null
  },
  '$original': {
    id: '019840bf-6aa3-75e6-bee8-7c931db59490',
    createdAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
    updatedAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
    isDefault: true,
    userPoolId: 'foo',
    clientName: 'bar',
    clientId: null
  },
  '$preloaded': {},
  '$extras': {},
  '$sideloaded': {},
  '$isPersisted': true,
  '$isDeleted': false,
  '$isLocal': true,
  isDefault: true,
  userPoolId: 'foo',
  clientName: 'bar',
  id: '019840bf-6aa3-75e6-bee8-7c931db59490',
  createdAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
  updatedAt: DateTime { ts: 2025-07-25T08:42:23.270+00:00, zone: UTC, locale: en-US },
  clientId: null // <-- Exists with correct null value as expected!
}

It is weird that the nullable clientId is just... not there in the model. Of course my IDE will say it is string | null and that the if-clause work as expected, but the truth is that the expected behavior of Lucid does not match the reality.

Reproduction repo

No response

[thetutlage]

It is expected, you can initiate the property with a null value. declare clientId: string | null = null.

The model properties are defined as if the model is hydrated with all the values from the Database. Which is ofcourse not true when you first instantiate the model instance locally without making a database query.

This is because, a class cannot have multiple representations. So you either have to assume the model is fully hydrated or assume it is very hydrated and define type properties to be a union of undefined.

[thedomeffm]

When it is the "correct" behavior of lucid than we should add this at least in the lucid example of Models > Defining columns!

=> https://lucid.adonisjs.com/docs/models#defining-columns

Because the example is misleading:

import { DateTime } from 'luxon'
import { BaseModel, column } from '@adonisjs/lucid/orm'

export default class User extends BaseModel {
  @column({ isPrimary: true })
  declare id: number

  @column()
  declare username: string

  @column()
  declare email: string

  @column({ serializeAs: null })
  declare password: string

  @column()
  declare avatarUrl: string | null // <----

  @column.dateTime({ autoCreate: true })
  declare createdAt: DateTime

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  declare updatedAt: DateTime
}

I would strictly recommend via the documentation to initiate the property with a null when it's nullable.

I am sure i am not the only one who thought that the ORM is initiate the avatarUrl with null. And the types are misleading either add | undefined or initiate null.

[thetutlage]

Do you expect the same for other columns too? The email initiated with an empty string?

[thedomeffm]

Do you expect the same for other columns too? The email initiated with an empty string?

Hmm. Somehow I thought it is is "not nullable" and it made sense, but with your question...

Good point.

As already mentioned in other issues I am coming from PHP and when accessing a types property that is not initialized (undefined in JS) you would receive an PHP Error. So it would not happen in PHPniverse.

But I guess some kind of type checking and initialization in Lucid is not planned or not wanted (also when thinking about performance).

To conclude my braindump here, I dont know Virk. Good question.
Probably for some new devs in TS/Adonis/Lucid we should add a more prominent hint that the default value is ALWAYS undefined?

[thedomeffm]

It is expected, you can initiate the property with a null value. declare clientId: string | null = null.

[...]

Problem 1 with declare

Hmm. It does not work with declare, right?

@column()
declare clientId: string | null = null;

results in the TS Error (with the default Adonis TS settings) TS1039: Initializers are not allowed in ambient contexts

I guess we're declaring it so the declare must be removed?

@column()
clientId: string | null = null;

Or is it best practice to add public?

@column()
public clientId: string | null = null;

Problem 2 with declare on relations

Wanted to adapt it on relations too, but I get an TypeScript Error.

class Tenant {

  // ...
  @hasOne(() => TenantOidcSetting)
  public oidcSetting: HasOne<typeof TenantOidcSetting> | null = null;
}

await tenant.load('oidcSetting'); // `TS2769: No overload matches this call.` and `Argument of type "oidcSetting" is not assignable to parameter of type ExtractModelRelations<Tenant>`

I guess the oidcSetting does not get recognized as a ExtractModelRelations<Tenant> when using public and null as default value.